diff --git a/.chloggen/add_k8s_fs_metrics.yaml b/.chloggen/add_k8s_fs_metrics.yaml new file mode 100644 index 000000000..f3870cb2d --- /dev/null +++ b/.chloggen/add_k8s_fs_metrics.yaml @@ -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: k8s + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add k8s node, pod, container filesystem metrics + +# 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: [1488] + +# (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: diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index e60961c2d..943c3f426 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -61,6 +61,7 @@ and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then: - [K8s Container metrics](#k8s-container-metrics) - [K8s ResourceQuota metrics](#k8s-resourcequota-metrics) - [K8s Node condition metrics](#k8s-node-condition-metrics) + - [K8s Filesystem metrics](#k8s-filesystem-metrics) @@ -370,3 +371,28 @@ The changes in their metrics are the following: | `k8s.node.condition_*` | `k8s.node.condition.status` metric [0,1] with attribute `k8s.node.condition.type` for the different conditions and `k8s.node.condition.status` for true/false/unknown | + +### K8s Filesystem metrics + +The K8s Filesystem metrics implemented by the Collector and specifically the +[k8scluster](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.115.0/receiver/k8sclusterreceiver/documentation.md) +receiver were introduced as semantic conventions in +[#2392](https://github.com/open-telemetry/semantic-conventions/pull/2392) + +The changes in their metrics are the following: + + + +| Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | +|------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| `k8s.node.filesystem.available` gauge | `k8s.node.filesystem.available` updowncounter | +| `k8s.node.filesystem.capacity` gauge | `k8s.node.filesystem.capacity` updowncounter | +| `k8s.node.filesystem.usage` gauge | `k8s.node.filesystem.usage` updowncounter | +| `k8s.pod.filesystem.available` gauge | `k8s.pod.filesystem.available` updowncounter | +| `k8s.pod.filesystem.capacity` gauge | `k8s.pod.filesystem.capacity` updowncounter | +| `k8s.pod.filesystem.usage` gauge | `k8s.pod.filesystem.usage` updowncounter | +| `container.filesystem.available` gauge | `container.filesystem.available` updowncounter | +| `container.filesystem.capacity` gauge | `container.filesystem.capacity` updowncounter | +| `container.filesystem.usage` gauge | `container.filesystem.usage` updowncounter | + + diff --git a/docs/system/container-metrics.md b/docs/system/container-metrics.md index fd859e4e2..b2646529d 100644 --- a/docs/system/container-metrics.md +++ b/docs/system/container-metrics.md @@ -12,6 +12,20 @@ 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.uptime`](#metric-containeruptime) +- [Metric: `container.cpu.time`](#metric-containercputime) +- [Metric: `container.cpu.usage`](#metric-containercpuusage) +- [Metric: `container.memory.usage`](#metric-containermemoryusage) +- [Metric: `container.disk.io`](#metric-containerdiskio) +- [Metric: `container.network.io`](#metric-containernetworkio) +- [Metric: `container.filesystem.available`](#metric-containerfilesystemavailable) +- [Metric: `container.filesystem.capacity`](#metric-containerfilesystemcapacity) +- [Metric: `container.filesystem.usage`](#metric-containerfilesystemusage) + + + ### Metric: `container.uptime` This metric is [recommended][MetricRecommended]. @@ -219,6 +233,83 @@ This metric is [opt-in][MetricOptIn]. +### Metric: `container.filesystem.available` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `container.filesystem.available` | UpDownCounter | `By` | Container filesystem available bytes [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/registry/entities/container.md#container) | + +**[1]:** In K8s, this metric is derived from the +[FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) +of the Kubelet's stats API. + + + + + + +### Metric: `container.filesystem.capacity` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `container.filesystem.capacity` | UpDownCounter | `By` | Container filesystem capacity [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/registry/entities/container.md#container) | + +**[1]:** In K8s, this metric is derived from the +[FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) +of the Kubelet's stats API. + + + + + + +### Metric: `container.filesystem.usage` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `container.filesystem.usage` | UpDownCounter | `By` | Container filesystem usage [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`container`](/docs/registry/entities/container.md#container) | + +**[1]:** This may not equal capacity - available. + +In K8s, this metric is derived from the +[FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) +of the Kubelet's stats API. + + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/system/k8s-metrics.md b/docs/system/k8s-metrics.md index f3cc932cb..9161df14a 100644 --- a/docs/system/k8s-metrics.md +++ b/docs/system/k8s-metrics.md @@ -24,6 +24,9 @@ and therefore inherit its attributes, like `k8s.pod.name` and `k8s.pod.uid`. - [Metric: `k8s.pod.memory.usage`](#metric-k8spodmemoryusage) - [Metric: `k8s.pod.network.io`](#metric-k8spodnetworkio) - [Metric: `k8s.pod.network.errors`](#metric-k8spodnetworkerrors) + - [Metric: `k8s.pod.filesystem.available`](#metric-k8spodfilesystemavailable) + - [Metric: `k8s.pod.filesystem.capacity`](#metric-k8spodfilesystemcapacity) + - [Metric: `k8s.pod.filesystem.usage`](#metric-k8spodfilesystemusage) - [Container metrics](#container-metrics) - [Metric: `k8s.container.status.state`](#metric-k8scontainerstatusstate) - [Metric: `k8s.container.status.reason`](#metric-k8scontainerstatusreason) @@ -39,6 +42,9 @@ and therefore inherit its attributes, like `k8s.pod.name` and `k8s.pod.uid`. - [Metric: `k8s.node.memory.usage`](#metric-k8snodememoryusage) - [Metric: `k8s.node.network.io`](#metric-k8snodenetworkio) - [Metric: `k8s.node.network.errors`](#metric-k8snodenetworkerrors) + - [Metric: `k8s.node.filesystem.available`](#metric-k8snodefilesystemavailable) + - [Metric: `k8s.node.filesystem.capacity`](#metric-k8snodefilesystemcapacity) + - [Metric: `k8s.node.filesystem.usage`](#metric-k8snodefilesystemusage) - [Deployment metrics](#deployment-metrics) - [Metric: `k8s.deployment.desired_pods`](#metric-k8sdeploymentdesired_pods) - [Metric: `k8s.deployment.available_pods`](#metric-k8sdeploymentavailable_pods) @@ -272,6 +278,83 @@ This metric is [recommended][MetricRecommended]. +### Metric: `k8s.pod.filesystem.available` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `k8s.pod.filesystem.available` | UpDownCounter | `By` | Pod filesystem available bytes [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.pod`](/docs/registry/entities/k8s.md#k8s-pod) | + +**[1]:** This metric is derived from the +[FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [PodStats.EphemeralStorage](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#PodStats) +of the Kubelet's stats API. + + + + + + +### Metric: `k8s.pod.filesystem.capacity` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `k8s.pod.filesystem.capacity` | UpDownCounter | `By` | Pod filesystem capacity [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.pod`](/docs/registry/entities/k8s.md#k8s-pod) | + +**[1]:** This metric is derived from the +[FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [PodStats.EphemeralStorage](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#PodStats) +of the Kubelet's stats API. + + + + + + +### Metric: `k8s.pod.filesystem.usage` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `k8s.pod.filesystem.usage` | UpDownCounter | `By` | Pod filesystem usage [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.pod`](/docs/registry/entities/k8s.md#k8s-pod) | + +**[1]:** This may not equal capacity - available. + +This metric is derived from the +[FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [PodStats.EphemeralStorage](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#PodStats) +of the Kubelet's stats API. + + + + + + ## Container metrics **Description:** Container level metrics captured under the namespace `k8s.container`. @@ -659,6 +742,83 @@ This metric is [recommended][MetricRecommended]. +### Metric: `k8s.node.filesystem.available` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `k8s.node.filesystem.available` | UpDownCounter | `By` | Node filesystem available bytes [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.node`](/docs/registry/entities/k8s.md#k8s-node) | + +**[1]:** This metric is derived from the +[FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [NodeStats.Fs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#NodeStats) +of the Kubelet's stats API. + + + + + + +### Metric: `k8s.node.filesystem.capacity` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `k8s.node.filesystem.capacity` | UpDownCounter | `By` | Node filesystem capacity [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.node`](/docs/registry/entities/k8s.md#k8s-node) | + +**[1]:** This metric is derived from the +[FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [NodeStats.Fs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#NodeStats) +of the Kubelet's stats API. + + + + + + +### Metric: `k8s.node.filesystem.usage` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | +| -------- | --------------- | ----------- | -------------- | --------- | ------ | +| `k8s.node.filesystem.usage` | UpDownCounter | `By` | Node filesystem usage [1] | ![Development](https://img.shields.io/badge/-development-blue) | [`k8s.node`](/docs/registry/entities/k8s.md#k8s-node) | + +**[1]:** This may not equal capacity - available. + +This metric is derived from the +[FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field +of the [NodeStats.Fs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#NodeStats) +of the Kubelet's stats API. + + + + + + ## Deployment metrics **Description:** Deployment level metrics captured under the namespace `k8s.deployment`. diff --git a/model/container/metrics.yaml b/model/container/metrics.yaml index 497da5606..bf86c5e13 100644 --- a/model/container/metrics.yaml +++ b/model/container/metrics.yaml @@ -102,3 +102,58 @@ groups: attributes: - ref: network.io.direction - ref: network.interface.name + + # container.filesystem.* metrics + - id: metric.container.filesystem.available + type: metric + metric_name: container.filesystem.available + stability: development + brief: "Container filesystem available bytes" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - container + note: | + In K8s, this metric is derived from the + [FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) + of the Kubelet's stats API. + - id: metric.container.filesystem.capacity + type: metric + metric_name: container.filesystem.capacity + stability: development + brief: "Container filesystem capacity" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - container + note: | + In K8s, this metric is derived from the + [FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) + of the Kubelet's stats API. + - id: metric.container.filesystem.usage + type: metric + metric_name: container.filesystem.usage + stability: development + brief: "Container filesystem usage" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - container + note: | + This may not equal capacity - available. + + In K8s, this metric is derived from the + [FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [ContainerStats.Rootfs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#ContainerStats) + of the Kubelet's stats API. diff --git a/model/k8s/metrics.yaml b/model/k8s/metrics.yaml index cb3d0bfab..eae084e15 100644 --- a/model/k8s/metrics.yaml +++ b/model/k8s/metrics.yaml @@ -91,6 +91,61 @@ groups: - ref: network.interface.name - ref: network.io.direction + # k8s.pod.filesystem.* metrics + - id: metric.k8s.pod.filesystem.available + type: metric + metric_name: k8s.pod.filesystem.available + stability: development + brief: "Pod filesystem available bytes" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - k8s.pod + note: | + This metric is derived from the + [FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [PodStats.EphemeralStorage](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#PodStats) + of the Kubelet's stats API. + - id: metric.k8s.pod.filesystem.capacity + type: metric + metric_name: k8s.pod.filesystem.capacity + stability: development + brief: "Pod filesystem capacity" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - k8s.pod + note: | + This metric is derived from the + [FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [PodStats.EphemeralStorage](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#PodStats) + of the Kubelet's stats API. + - id: metric.k8s.pod.filesystem.usage + type: metric + metric_name: k8s.pod.filesystem.usage + stability: development + brief: "Pod filesystem usage" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - k8s.pod + note: | + This may not equal capacity - available. + + This metric is derived from the + [FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [PodStats.EphemeralStorage](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#PodStats) + of the Kubelet's stats API. + # k8s.container.* metrics - id: metric.k8s.container.status.state type: metric @@ -245,6 +300,61 @@ groups: - k8s.node unit: "{cpu}" + # k8s.node.filesystem.* metrics + - id: metric.k8s.node.filesystem.available + type: metric + metric_name: k8s.node.filesystem.available + stability: development + brief: "Node filesystem available bytes" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - k8s.node + note: | + This metric is derived from the + [FsStats.AvailableBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [NodeStats.Fs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#NodeStats) + of the Kubelet's stats API. + - id: metric.k8s.node.filesystem.capacity + type: metric + metric_name: k8s.node.filesystem.capacity + stability: development + brief: "Node filesystem capacity" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - k8s.node + note: | + This metric is derived from the + [FsStats.CapacityBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [NodeStats.Fs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#NodeStats) + of the Kubelet's stats API. + - id: metric.k8s.node.filesystem.usage + type: metric + metric_name: k8s.node.filesystem.usage + stability: development + brief: "Node filesystem usage" + instrument: updowncounter + unit: "By" + annotations: + code_generation: + metric_value_type: int + entity_associations: + - k8s.node + note: | + This may not equal capacity - available. + + This metric is derived from the + [FsStats.UsedBytes](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#FsStats) field + of the [NodeStats.Fs](https://pkg.go.dev/k8s.io/kubelet@v0.33.0/pkg/apis/stats/v1alpha1#NodeStats) + of the Kubelet's stats API. + # k8s.node.memory.* metrics - id: metric.k8s.node.memory.usage type: metric