Skip to content

Commit 0941ebb

Browse files
ChrsMarkjoaopgrassi
ChrsMark
and
joaopgrassi
authored
Add container metric fields (from ECS) (#282)
Signed-off-by: ChrsMark <[email protected]> Co-authored-by: Joao Grassi <[email protected]>
1 parent 4368358 commit 0941ebb

File tree

5 files changed

+203
-0
lines changed

5 files changed

+203
-0
lines changed

‎.chloggen/add_new_container_metrics.yaml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Use this changelog template to create an entry for release notes.
2+
#
3+
# If your change doesn't affect end users you should instead start
4+
# your pull request title with [chore] or use the "Skip Changelog" label.
5+
6+
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
7+
change_type: "enhancement"
8+
9+
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
10+
component: "container"
11+
12+
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
13+
note: "Add new container metrics for `cpu`, `memory`, `disk` and `network`"
14+
15+
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
16+
issues: [282, 72]
17+
18+
# (Optional) One or more lines of additional information to render under the primary note.
19+
# These lines will be padded with 2 spaces and then inserted directly into the document.
20+
# Use pipe (|) for multiline entries.
21+
subtext:

‎docs/attributes-registry/container.md

+9
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
| `container.command` | string | The command used to run the container (i.e. the command name). [1] | `otelcontribcol` |
1212
| `container.command_args` | string[] | All the command arguments (including the command/executable itself) run by the container. [2] | `[otelcontribcol, --config, config.yaml]` |
1313
| `container.command_line` | string | The full command run by the container as a single string representing the full command. [2] | `otelcontribcol --config config.yaml` |
14+
| `container.cpu.state` | string | The CPU state for this data point. | `user`; `kernel` |
1415
| `container.id` | string | Container ID. Usually a UUID, as for example used to [identify Docker containers](https://docs.docker.com/engine/reference/run/#container-identification). The UUID might be abbreviated. | `a3bf90e006b2` |
1516
| `container.image.id` | string | Runtime specific image identifier. Usually a hash algorithm followed by a UUID. [2] | `sha256:19c92d0a00d1b66d897bceaa7319bee0dd38a10a851c60bcec9474aa3f01e50f` |
1617
| `container.image.name` | string | Name of the image the container was built on. | `gcr.io/opentelemetry/operator` |
@@ -27,4 +28,12 @@ K8s defines a link to the container registry repository with digest `"imageID":
2728
The ID is assinged by the container runtime and can vary in different environments. Consider using `oci.manifest.digest` if it is important to identify the same image in different environments/runtimes.
2829

2930
**[3]:** [Docker](https://docs.docker.com/engine/api/v1.43/#tag/Image/operation/ImageInspect) and [CRI](https://github.com/kubernetes/cri-api/blob/c75ef5b473bbe2d0a4fc92f82235efd665ea8e9f/pkg/apis/runtime/v1/api.proto#L1237-L1238) report those under the `RepoDigests` field.
31+
32+
`container.cpu.state` 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.
33+
34+
| Value | Description |
35+
|---|---|
36+
| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). |
37+
| `system` | When CPU is used by the system (host OS) |
38+
| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). |
3039
<!-- endsemconv -->

‎docs/system/container-metrics.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
linkTitle: Container
3+
--->
4+
5+
# Semantic Conventions for Container Metrics
6+
7+
**Status**: [Experimental][DocumentStatus]
8+
9+
## Container Metrics
10+
11+
### Metric: `container.cpu.time`
12+
13+
This metric is [opt-in][MetricOptIn].
14+
15+
<!-- semconv metric.container.cpu.time(metric_table) -->
16+
| Name | Instrument Type | Unit (UCUM) | Description |
17+
| -------- | --------------- | ----------- | -------------- |
18+
| `container.cpu.time` | Counter | `s` | Total CPU time consumed [1] |
19+
20+
**[1]:** Total CPU time consumed by the specific container on all available CPU cores
21+
<!-- endsemconv -->
22+
23+
<!-- semconv metric.container.cpu.time(full) -->
24+
| Attribute | Type | Description | Examples | Requirement Level |
25+
|---|---|---|---|---|
26+
| [`container.cpu.state`](../attributes-registry/container.md) | string | The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels. | `user`; `kernel` | Opt-In |
27+
28+
`container.cpu.state` 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.
29+
30+
| Value | Description |
31+
|---|---|
32+
| `user` | When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows). |
33+
| `system` | When CPU is used by the system (host OS) |
34+
| `kernel` | When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows). |
35+
<!-- endsemconv -->
36+
37+
### Metric: `container.memory.usage`
38+
39+
This metric is [opt-in][MetricOptIn].
40+
41+
<!-- semconv metric.container.memory.usage(metric_table) -->
42+
| Name | Instrument Type | Unit (UCUM) | Description |
43+
| -------- | --------------- | ----------- | -------------- |
44+
| `container.memory.usage` | Counter | `By` | Memory usage of the container. [1] |
45+
46+
**[1]:** Memory usage of the container.
47+
<!-- endsemconv -->
48+
49+
<!-- semconv metric.container.memory.usage(full) -->
50+
<!-- endsemconv -->
51+
52+
### Metric: `container.disk.io`
53+
54+
This metric is [opt-in][MetricOptIn].
55+
56+
<!-- semconv metric.container.disk.io(metric_table) -->
57+
| Name | Instrument Type | Unit (UCUM) | Description |
58+
| -------- | --------------- | ----------- | -------------- |
59+
| `container.disk.io` | Counter | `By` | Disk bytes for the container. [1] |
60+
61+
**[1]:** The total number of bytes read/written successfully (aggregated from all disks).
62+
<!-- endsemconv -->
63+
64+
<!-- semconv metric.container.disk.io(full) -->
65+
| Attribute | Type | Description | Examples | Requirement Level |
66+
|---|---|---|---|---|
67+
| [`disk.io.direction`](../attributes-registry/disk.md) | string | The disk IO operation direction. | `read` | Recommended |
68+
| `system.device` | string | The device identifier | `(identifier)` | Recommended |
69+
70+
`disk.io.direction` MUST be one of the following:
71+
72+
| Value | Description |
73+
|---|---|
74+
| `read` | read |
75+
| `write` | write |
76+
<!-- endsemconv -->
77+
78+
### Metric: `container.network.io`
79+
80+
This metric is [opt-in][MetricOptIn].
81+
82+
<!-- semconv metric.container.network.io(metric_table) -->
83+
| Name | Instrument Type | Unit (UCUM) | Description |
84+
| -------- | --------------- | ----------- | -------------- |
85+
| `container.network.io` | Counter | `By` | Network bytes for the container. [1] |
86+
87+
**[1]:** The number of bytes sent/received on all network interfaces by the container.
88+
<!-- endsemconv -->
89+
90+
<!-- semconv metric.container.network.io(full) -->
91+
| Attribute | Type | Description | Examples | Requirement Level |
92+
|---|---|---|---|---|
93+
| [`network.io.direction`](../attributes-registry/network.md) | string | The network IO operation direction. | `transmit` | Recommended |
94+
| `system.device` | string | The device identifier | `(identifier)` | Recommended |
95+
96+
`network.io.direction` MUST be one of the following:
97+
98+
| Value | Description |
99+
|---|---|
100+
| `transmit` | transmit |
101+
| `receive` | receive |
102+
<!-- endsemconv -->
103+
104+
[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md
105+
[MetricOptIn]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/metrics/metric-requirement-level.md#opt-in

‎model/metrics/container.yaml

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
groups:
2+
# container.cpu.* metrics and attribute group
3+
- id: metric.container.cpu.time
4+
type: metric
5+
metric_name: container.cpu.time
6+
brief: "Total CPU time consumed"
7+
note: >
8+
Total CPU time consumed by the specific container on all available CPU cores
9+
instrument: counter
10+
unit: "s"
11+
attributes:
12+
- ref: container.cpu.state
13+
brief: "The CPU state for this data point. A container SHOULD be characterized _either_ by data points with no `state` labels, _or only_ data points with `state` labels."
14+
requirement_level: opt_in
15+
16+
# container.memory.* metrics and attribute group
17+
- id: metric.container.memory.usage
18+
type: metric
19+
metric_name: container.memory.usage
20+
brief: "Memory usage of the container."
21+
note: >
22+
Memory usage of the container.
23+
instrument: counter
24+
unit: "By"
25+
26+
# container.disk.io.* metrics and attribute group
27+
- id: metric.container.disk.io
28+
type: metric
29+
metric_name: container.disk.io
30+
brief: "Disk bytes for the container."
31+
note: >
32+
The total number of bytes read/written
33+
successfully (aggregated from all disks).
34+
instrument: counter
35+
unit: "By"
36+
attributes:
37+
- ref: disk.io.direction
38+
- ref: system.device
39+
40+
# container.network.io.* metrics and attribute group
41+
- id: metric.container.network.io
42+
type: metric
43+
metric_name: container.network.io
44+
brief: "Network bytes for the container."
45+
note: >
46+
The number of bytes sent/received
47+
on all network interfaces
48+
by the container.
49+
instrument: counter
50+
unit: "By"
51+
attributes:
52+
- ref: network.io.direction
53+
- ref: system.device

‎model/registry/container.yaml

+15
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,18 @@ groups:
9595
brief: >
9696
Container labels, `<key>` being the label name, the value being the label value.
9797
examples: [ 'container.label.app=nginx' ]
98+
- id: cpu.state
99+
brief: "The CPU state for this data point."
100+
type:
101+
allow_custom_values: true
102+
members:
103+
- id: user
104+
value: 'user'
105+
brief: "When tasks of the cgroup are in user mode (Linux). When all container processes are in user mode (Windows)."
106+
- id: system
107+
value: 'system'
108+
brief: "When CPU is used by the system (host OS)"
109+
- id: kernel
110+
value: 'kernel'
111+
brief: "When tasks of the cgroup are in kernel mode (Linux). When all container processes are in kernel mode (Windows)."
112+
examples: ["user", "kernel"]

0 commit comments

Comments
 (0)