open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add container.cpu.usage metric (#1128) 

Signed-off-by: ChrsMark <chrismarkou92@gmail.com>
Co-authored-by: Helen <56097766+heyams@users.noreply.github.com>
Co-authored-by: Pablo Baeyens <pbaeyens31+github@gmail.com>
This commit is contained in:
Christos Markou 2024-08-05 17:43:45 +03:00 committed by GitHub
parent 18b35558bc
commit f48852ff25
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 109 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
.chloggen/add_container_cpu_usage.yaml Executable file
View File

@ -0,0 +1,22 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: enhancement
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: container
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Add container.cpu.usage metric
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
issues: [1128]
# (Optional) One or more lines of additional information to render under the primary note.
# These lines will be padded with 2 spaces and then inserted directly into the document.
# Use pipe (|) for multiline entries.
subtext:

70
docs/system/container-metrics.md
View File

@ -8,6 +8,10 @@ linkTitle: Container
## Container Metrics
This document describes instruments and attributes for common container level
metrics in OpenTelemetry. These metrics are collected from technology-specific,
well-defined APIs (e.g. Kubelet's API or container runtimes).
### Metric: `container.cpu.time`
This metric is [opt-in][MetricOptIn].
@ -42,10 +46,74 @@ This metric is [opt-in][MetricOptIn].
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** Following states SHOULD be used: `user`, `system`, `kernel`
**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
| Value | Description | Stability |
|---|---|---|
| `idle` | idle | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `interrupt` | interrupt | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `iowait` | iowait | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `kernel` | kernel | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `nice` | nice | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `steal` | steal | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `system` | system | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `user` | user | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `container.cpu.usage`
This metric is [opt-in][MetricOptIn].
<!-- semconv metric.container.cpu.usage(metric_table) -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
| `container.cpu.usage` | Gauge | `{cpu}` | Container's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** CPU usage of the specific container on all available CPU cores, averaged over the sample window
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
<!-- semconv metric.container.cpu.usage(full) -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`cpu.mode`](/docs/attributes-registry/cpu.md) | string | The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels. [1] | `user`; `system` | `Conditionally Required` [2] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** Following states SHOULD be used: `user`, `system`, `kernel`
**[2]:** Required if mode is available, i.e. metrics coming from the Docker Stats API.
`cpu.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

19
model/metrics/container.yaml
View File

@ -13,7 +13,24 @@ groups:
- ref: cpu.mode
brief: "The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels."
note: "Following states SHOULD be used: `user`, `system`, `kernel`"
requirement_level: opt_in
requirement_level:
conditionally_required: Required if mode is available, i.e. metrics coming from the Docker Stats API.
- id: metric.container.cpu.usage
type: metric
metric_name: container.cpu.usage
stability: experimental
brief: "Container's CPU usage, measured in cpus. Range from 0 to the number of allocatable CPUs"
note: >
CPU usage of the specific container on all available CPU cores, averaged over the sample window
instrument: gauge
unit: "{cpu}"
attributes:
- ref: cpu.mode
brief: "The CPU mode for this data point. A container's CPU metric SHOULD be characterized _either_ by data points with no `mode` labels, _or only_ data points with `mode` labels."
note: "Following states SHOULD be used: `user`, `system`, `kernel`"
requirement_level:
conditionally_required: Required if mode is available, i.e. metrics coming from the Docker Stats API.
# container.memory.* metrics and attribute group
- id: metric.container.memory.usage