> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/system/container-metrics/ # コンテナメトリクスに関するセマンティック規約 **ステータス**: [Development][DocumentStatus] ## コンテナメトリクス この文書では、OpenTelemetryにおける一般的なコンテナレベルのメトリクスのInstrumentと属性について説明します。 これらのメトリクスは、技術固有の明確に定義されたAPI（KubeletのAPIやコンテナランタイムなど）から収集されます。 ### メトリクス: `container.uptime` このメトリクスは[推奨][MetricRecommended]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.uptime` | Gauge | `s` | コンテナが実行されている時間。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 計装は、`double`型のgaugeを使用し、利用可能な最高精度の浮動小数点数で稼働時間を秒単位で計測すべきです（SHOULD）。 実際の精度は計装とオペレーティングシステムに依存します。 ### メトリクス: `container.cpu.time` このメトリクスは[推奨][MetricRecommended]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.cpu.time` | Counter | `s` | 消費された合計CPU時間。[1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 利用可能なすべてのCPUコアにおいて、その特定のコンテナが消費したCPU時間 **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`cpu.mode`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cpu/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [1] | string | このデータポイントのCPUモード。コンテナのCPUメトリクスは、`mode`ラベルを持たないデータポイント、または`mode`ラベルを持つデータポイントの*いずれか*のみによって特徴付けられるべきです（SHOULD）。[2] | `user`; `system` | **[1] `cpu.mode`:** modeが利用可能な場合、つまりDocker Stats API、containerd statsまたはcAdvisorから取得されたメトリクスの場合は必須。 **[2] `cpu.mode`:** コンテナに利用可能であれば、次のモードを使用すべきです（SHOULD）: `user`、`system`。 [`opencontainers/cgroup`](https://pkg.go.dev/github.com/opencontainers/cgroups@v0.0.6#CpuUsage)、[Moby/Docker](https://pkg.go.dev/github.com/Moby/Moby@v28.5.2+incompatible/api/types/container#CPUUsage)、[cAdvisor](https://pkg.go.dev/github.com/google/cadvisor@v0.56.2/info/v1#CpuUsage)のような実装では、それぞれの状態はcgroupの統計情報から直接取得されます。cgroup v1では、userモードとsystemモードは[cpuacct.stat](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/cpuacct.html#cpu-accounting-controller)ファイルのそれぞれ`user`統計と`system`統計から取得されます。cgroup v2では、userモードとsystemモードは[cpu.stat](https://docs.kernel.org/admin-guide/cgroup-v2.html#cpu-interface-files)ファイルのそれぞれ`user_usec`統計と`system_usec`統計から取得されます。 Kubernetesは、Kubelet の statsAPIを通じて合計CPU時間（[cpu.stat.usage_usec](https://docs.kernel.org/admin-guide/cgroup-v2.html#cpu-interface-files)）のみを公開するため、このメトリクスはすべてのモードの合計を意味するmode属性なしで報告すべきです。 純粋なコンテナ環境では、通常CPUのモードが利用可能であり、cpu.modeを報告すべきです。その場合、各モードのCPU時間を合計すると、総CPU時間が得られます。 --- `cpu.mode`には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `idle` | Idle | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `interrupt` | Interrupt | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `iowait` | IO Wait | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `nice` | Nice | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `steal` | Steal | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `system` | System | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `user` | User | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### メトリクス: `container.cpu.usage` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.cpu.usage` | Gauge | `{cpu}` | コンテナのCPU使用率。CPU数で計測され、0から割り当て可能なCPU数までの範囲を取ります。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 利用可能なすべてのCPUコアにおける、その特定のコンテナのCPU使用率。これは、計測間隔における累積CPU時間（container.cpu.time）の変化量を、経過時間で割ることで算出されます: usageCores = (cpuTimeEnd - cpuTimeStart) / elapsedSeconds **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`cpu.mode`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cpu/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` [1] | string | このデータポイントのCPUモード。コンテナのCPUメトリクスは、`mode`ラベルを持たないデータポイント、または`mode`ラベルを持つデータポイントの*いずれか*のみによって特徴付けられるべきです（SHOULD）。[2] | `user`; `system` | **[1] `cpu.mode`:** modeが利用可能な場合、つまりDocker Stats API、containerd statsまたはcAdvisorから取得されたメトリクスの場合は必須。 **[2] `cpu.mode`:** コンテナに利用可能であれば、次のモードを使用すべきです（SHOULD）: `user`、`system`。 --- `cpu.mode`には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `idle` | Idle | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `interrupt` | Interrupt | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `iowait` | IO Wait | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `nice` | Nice | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `steal` | Steal | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `system` | System | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `user` | User | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### メトリクス: `container.memory.usage` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.usage` | UpDownCounter | `By` | コンテナのメモリ使用量。[1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** アクセスされた時期にかかわらず、すべてのメモリを含む現在のメモリ使用量。 一般に、このメトリクスは[cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics)、特に`container_memory_usage_bytes`メトリクスから導出できます。 K8sでは、このメトリクスはKubeletのstats APIの[ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats)の[MemoryStats.UsageBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats)フィールドから導出されます。 ### メトリクス: `container.memory.available` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.available` | UpDownCounter | `By` | コンテナで利用可能なメモリ。[1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 利用可能なメモリ。これは、メモリ上限 - workingSetBytesとして定義されます。メモリ上限が未定義の場合、利用可能バイト数は省略されます。 一般に、このメトリクスは[cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics)から、`container_spec_memory_limit_bytes`メトリクスから`container_memory_working_set_bytes`メトリクスを減算することで導出できます。 K8sでは、このメトリクスはKubeletのstats APIの[ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats)の[MemoryStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats)フィールドから導出されます。 ### メトリクス: `container.memory.rss` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.rss` | UpDownCounter | `By` | コンテナのメモリRSS。[1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 一般に、このメトリクスは[cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics)、特に`container_memory_rss`メトリクスから導出できます。 K8sでは、このメトリクスはKubeletのstats APIの[ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats)の[MemoryStats.RSSBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats)フィールドから導出されます。 ### メトリクス: `container.memory.working_set` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.memory.working_set` | UpDownCounter | `By` | コンテナのworking setメモリ。[1] | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 一般に、このメトリクスは[cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics)、特に`container_memory_working_set_bytes`メトリクスから導出できます。 K8sでは、このメトリクスはKubeletのstats APIの[ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats)の[MemoryStats.WorkingSetBytes](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats)フィールドから導出されます。 ### メトリクス: `container.paging.faults` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.paging.faults` | Counter | `{fault}` | コンテナのメモリページングフォルト。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 一般に、このメトリクスは[cadvisor](https://github.com/google/cadvisor/blob/v0.53.0/docs/storage/prometheus.md#prometheus-container-metrics)、特に`container_memory_failures_total{failure_type=pgfault, scope=container}`メトリクスと`container_memory_failures_total{failure_type=pgmajfault, scope=container}`メトリクスから導出できます。 K8sでは、このメトリクスはKubeletのstats APIの[ContainerStats.Memory](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#ContainerStats)の[MemoryStats.PageFaults](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats)フィールドと[MemoryStats.MajorPageFaults](https://pkg.go.dev/k8s.io/kubelet@v0.34.0/pkg/apis/stats/v1alpha1#MemoryStats)フィールドから導出されます。 **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`system.paging.fault.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/system/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | ページングフォルトの種別 | `minor` | --- `system.paging.fault.type`には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `major` | major | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `minor` | minor | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### メトリクス: `container.disk.io` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.disk.io` | Counter | `By` | コンテナのディスクバイト数。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** 正常に読み書きされたバイト数の合計（すべてのディスクから集計）。 **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`disk.io.direction`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/disk/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | ディスクIO操作の方向。 | `read` | | [`system.device`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/system/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | デバイス識別子 | `(identifier)` | --- `disk.io.direction`には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `read` | read | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `write` | write | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### メトリクス: `container.network.io` このメトリクスは[opt-in][MetricOptIn]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.network.io` | Counter | `By` | コンテナのネットワークバイト数。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** コンテナのすべてのネットワークインターフェースで送受信されたバイト数。 **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`network.interface.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | ネットワークインターフェース名。 | `lo`; `eth0` | | [`network.io.direction`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/network/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | 観測対象ホストの物理または仮想ネットワークインターフェースの視点から見たトラフィックの方向。ステートフルな接続やネットワークフローの論理的な方向を表すために使用すべきではありません。 | `transmit` | --- `network.io.direction`には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `receive` | receive | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `transmit` | transmit | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | ### メトリクス: `container.filesystem.available` このメトリクスは[推奨][MetricRecommended]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.filesystem.available` | UpDownCounter | `By` | コンテナのファイルシステムの利用可能バイト数。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** K8sでは、このメトリクスはKubeletのstats APIの [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats)の [FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats)フィールドから導出されます。 ### メトリクス: `container.filesystem.capacity` このメトリクスは[推奨][MetricRecommended]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.filesystem.capacity` | UpDownCounter | `By` | コンテナのファイルシステム容量。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** K8sでは、このメトリクスはKubeletのstats APIの [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats)の [FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats)フィールドから導出されます。 ### メトリクス: `container.filesystem.usage` このメトリクスは[推奨][MetricRecommended]です。 | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `container.filesystem.usage` | UpDownCounter | `By` | コンテナのファイルシステム使用量。[1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](https://opentelemetry.io/docs/specs/semconv/registry/entities/container/#container) | **[1]:** これはcapacity - availableと等しくない場合があります。 K8sでは、このメトリクスはKubeletのstats APIの [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats)の [FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats)フィールドから導出されます。 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricOptIn]: /works/otel-specs-ja/semconv/general/metric-requirement-level/#opt-in [MetricRecommended]: /works/otel-specs-ja/semconv/general/metric-requirement-level/#recommended