[receiver/k8s_cluster] Sync allocatable metric names with the latest semconv

.chloggen/k8scluster-allocatable.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: receiver/k8s_cluster
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Sync allocatable metric names with the latest semconv"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [40708]
+
+# (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:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

receiver/k8sclusterreceiver/README.md

@@ -93,6 +93,11 @@ Example:
 The full list of settings exposed for this receiver are documented in [config.go](./config.go)
 with detailed sample configurations in [testdata/config.yaml](./testdata/config.yaml).
 
+**Note** that with the introduction of the [semconv.k8s.enableStable](#semconvk8senablestable) feature gate, the metrics for the allocatable resource types
+(`k8s.node.allocatable.cpu`, `k8s.node.allocatable.ephemeral_storage`, `k8s.node.allocatable.memory`, `k8s.node.allocatable.pods`) are enabled/disabled via the metrics section, and are represented by up/down counters, rather than gauges.
+To activate the feature flag, start the collector with `--feature-gates=+semconv.k8s.enableStable`.
+To disable the old representation of the allocatable metrics (`k8s.node.allocatable_cpu`, `k8s.node.allocatable_ephemeral_storage`, `k8s.node.allocatable_memory`, `k8s.node.allocatable_pods`) disable the [semconv.k8s.disableLegacy](#semconvk8sdisablelegacy) feature flag with `--feature-gates=-semconv.k8s.disableLegacy`
+
 ### k8s_leader_elector
 Provide name of the k8s leader elector extension defined in config. This allows multiple instances of k8s cluster
 receiver to be executed on a cluster. At a given time only the pod which has the is active.
@@ -453,3 +458,28 @@ Add the following rules to your ClusterRole:
   - watch
 ```
 
+## Feature Gates
+
+### `semconv.k8s.enableStable`
+
+The `semconv.k8s.enableStable` [feature gate](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md#collector-feature-gates) enables the SemConv valid format of the node allocatable metrics reported by the receiver.
+The feature gate is in `alpha` stage, which means it is disabled by default.
+
+If enabled, the SemConv valid format of the node allocatable metrics are reported (if enabled via the metrics section):
+
+- `k8s.node.allocatable.cpu`
+- `k8s.node.allocatable.ephemeral_storage`
+- `k8s.node.allocatable.memory`
+- `k8s.node.allocatable.pods`
+
+### `semconv.k8s.disableLegacy`
+
+The `semconv.k8s.disableLegacy` [feature gate](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md#collector-feature-gates) disables the old, non-SemConv valid format of the node allocatable metrics reported by the receiver.
+The feature gate is in `alpha` stage, which means it is disabled by default.
+
+If disabled, the old format of the node allocatable metrics are reported:
+
+- `k8s.node.allocatable_cpu`
+- `k8s.node.allocatable_ephemeral_storage`
+- `k8s.node.allocatable_memory`
+- `k8s.node.allocatable_pods`

receiver/k8sclusterreceiver/documentation.md

@@ -228,6 +228,38 @@ The current phase of namespaces (1 for active and 0 for terminating)
 | ---- | ----------- | ---------- | --------- |
 |  | Gauge | Int | development |
 
+### k8s.node.allocatable.cpu
+
+Amount of cpu allocatable on the node
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| {cpu} | Sum | Double | Unspecified | false |
+
+### k8s.node.allocatable.ephemeral_storage
+
+Amount of ephemeral-storage allocatable on the node
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| By | Sum | Int | Unspecified | false |
+
+### k8s.node.allocatable.memory
+
+Amount of memory allocatable on the node
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| By | Sum | Int | Unspecified | false |
+
+### k8s.node.allocatable.pods
+
+Amount of pods allocatable on the node
+
+| Unit | Metric Type | Value Type | Aggregation Temporality | Monotonic |
+| ---- | ----------- | ---------- | ----------------------- | --------- |
+| {pod} | Sum | Int | Unspecified | false |
+
 ### k8s.pod.phase
 
 Current phase of the pod (1 - Pending, 2 - Running, 3 - Succeeded, 4 - Failed, 5 - Unknown)

receiver/k8sclusterreceiver/go.mod

@@ -25,6 +25,7 @@ require (
 	go.opentelemetry.io/collector/confmap/xconfmap v0.138.1-0.20251021231522-c657d5d4e920
 	go.opentelemetry.io/collector/consumer v1.44.1-0.20251021231522-c657d5d4e920
 	go.opentelemetry.io/collector/consumer/consumertest v0.138.1-0.20251021231522-c657d5d4e920
+	go.opentelemetry.io/collector/featuregate v1.44.1-0.20251021231522-c657d5d4e920
 	go.opentelemetry.io/collector/filter v0.138.1-0.20251021231522-c657d5d4e920
 	go.opentelemetry.io/collector/pdata v1.44.1-0.20251021231522-c657d5d4e920
 	go.opentelemetry.io/collector/pipeline v1.44.1-0.20251021231522-c657d5d4e920
@@ -111,7 +112,6 @@ require (
 	go.opentelemetry.io/collector/extension v1.44.1-0.20251021231522-c657d5d4e920 // indirect
 	go.opentelemetry.io/collector/extension/extensionauth v1.44.1-0.20251021231522-c657d5d4e920 // indirect
 	go.opentelemetry.io/collector/extension/extensionmiddleware v0.138.1-0.20251021231522-c657d5d4e920 // indirect
-	go.opentelemetry.io/collector/featuregate v1.44.1-0.20251021231522-c657d5d4e920 // indirect
 	go.opentelemetry.io/collector/internal/sharedcomponent v0.138.1-0.20251021231522-c657d5d4e920 // indirect
 	go.opentelemetry.io/collector/internal/telemetry v0.138.1-0.20251021231522-c657d5d4e920 // indirect
 	go.opentelemetry.io/collector/pdata/pprofile v0.138.1-0.20251021231522-c657d5d4e920 // indirect