Add notes about resource correlation

Signed-off-by: ChrsMark <[email protected]>
open-telemetry · Dec 14, 2024 · 1f91666 · 1f91666
1 parent 11e412e
commit 1f91666
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 16 deletions.
diff --git a/docs/system/k8s-metrics.md b/docs/system/k8s-metrics.md
@@ -397,7 +397,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.deployment.desired_pods` | UpDownCounter | `{pod}` | Number of desired replica pods in this deployment [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `replicas` field of the
-[K8s DeploymentSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentspec-v1-apps)
+[K8s DeploymentSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentspec-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.deployment`](../resource/k8s.md#deployment) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -420,7 +423,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.deployment.available_pods` | UpDownCounter | `{pod}` | Total number of available replica pods (ready for at least minReadySeconds) targeted by this deployment [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `availableReplicas` field of the
-[K8s DeploymentStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentstatus-v1-apps)
+[K8s DeploymentStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentstatus-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.deployment`](../resource/k8s.md#deployment) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -447,7 +453,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.replicaset.desired_pods` | UpDownCounter | `{pod}` | Number of desired replica pods in this replicaset [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `replicas` field of the
-[K8s ReplicaSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetspec-v1-apps)
+[K8s ReplicaSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetspec-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.replicaset`](../resource/k8s.md#replicaset) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -470,7 +479,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.replicaset.available_pods` | UpDownCounter | `{pod}` | Total number of available replica pods (ready for at least minReadySeconds) targeted by this replicaset [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `availableReplicas` field of the
-[K8s ReplicaSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetstatus-v1-apps)
+[K8s ReplicaSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetstatus-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.replicaset`](../resource/k8s.md#replicaset) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -547,7 +559,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.statefulset.desired_pods` | UpDownCounter | `{pod}` | Number of desired replica pods in this statefulset [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `replicas` field of the
-[K8s StatefulSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetspec-v1-apps)
+[K8s StatefulSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetspec-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -570,7 +585,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.statefulset.ready_pods` | UpDownCounter | `{pod}` | The number of replica pods created for this statefulset with a Ready Condition [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `readyReplicas` field of the
-[K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps)
+[K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -593,7 +611,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.statefulset.current_pods` | UpDownCounter | `{pod}` | The number of replica pods created by the statefulset controller from the statefulset version indicated by currentRevision [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `currentReplicas` field of the
-[K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps)
+[K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -616,7 +637,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.statefulset.updated_pods` | UpDownCounter | `{pod}` | Number of replica pods created by the statefulset controller from the statefulset version indicated by updateRevision [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `updatedReplicas` field of the
-[K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps)
+[K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->

diff --git a/model/k8s/metrics.yaml b/model/k8s/metrics.yaml
@@ -135,7 +135,10 @@ groups:
     brief: "Number of desired replica pods in this deployment"
     note: |
       This metric aligns with the `replicas` field of the
-      [K8s DeploymentSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentspec-v1-apps)
+      [K8s DeploymentSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentspec-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.deployment`](../resource/k8s.md#deployment) resource.
     instrument: updowncounter
     unit: "{pod}"
   - id: metric.k8s.deployment.available_pods
@@ -145,7 +148,10 @@ groups:
     brief: "Total number of available replica pods (ready for at least minReadySeconds) targeted by this deployment"
     note: |
       This metric aligns with the `availableReplicas` field of the
-      [K8s DeploymentStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentstatus-v1-apps)
+      [K8s DeploymentStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#deploymentstatus-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.deployment`](../resource/k8s.md#deployment) resource.
     instrument: updowncounter
     unit: "{pod}"
 
@@ -157,7 +163,10 @@ groups:
     brief: "Number of desired replica pods in this replicaset"
     note: |
       This metric aligns with the `replicas` field of the
-      [K8s ReplicaSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetspec-v1-apps)
+      [K8s ReplicaSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetspec-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.replicaset`](../resource/k8s.md#replicaset) resource.
     instrument: updowncounter
     unit: "{pod}"
   - id: metric.k8s.replicaset.available_pods
@@ -167,7 +176,10 @@ groups:
     brief: "Total number of available replica pods (ready for at least minReadySeconds) targeted by this replicaset"
     note: |
       This metric aligns with the `availableReplicas` field of the
-      [K8s ReplicaSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetstatus-v1-apps)
+      [K8s ReplicaSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicasetstatus-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.replicaset`](../resource/k8s.md#replicaset) resource.
     instrument: updowncounter
     unit: "{pod}"
 
@@ -177,6 +189,7 @@ groups:
     metric_name: k8s.replication_controller.desired_pods
     stability: experimental
     brief: "Number of desired replica pods in this replication controller"
+    # TODO: Add note for resource correlation once https://github.com/open-telemetry/semantic-conventions/issues/1656 is implemented
     note: |
       This metric aligns with the `replicas` field of the
       [K8s ReplicationControllerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicationcontrollerspec-v1-core)
@@ -187,6 +200,7 @@ groups:
     metric_name: k8s.replication_controller.available_pods
     stability: experimental
     brief: "Total number of available replica pods (ready for at least minReadySeconds) targeted by this replication controller"
+    # TODO: Add note for resource correlation once https://github.com/open-telemetry/semantic-conventions/issues/1656 is implemented
     note: |
       This metric aligns with the `availableReplicas` field of the
       [K8s ReplicationControllerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#replicationcontrollerstatus-v1-core)
@@ -201,7 +215,10 @@ groups:
     brief: "Number of desired replica pods in this statefulset"
     note: |
       This metric aligns with the `replicas` field of the
-      [K8s StatefulSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetspec-v1-apps)
+      [K8s StatefulSetSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetspec-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
     instrument: updowncounter
     unit: "{pod}"
   - id: metric.k8s.statefulset.ready_pods
@@ -211,7 +228,10 @@ groups:
     brief: "The number of replica pods created for this statefulset with a Ready Condition"
     note: |
       This metric aligns with the `readyReplicas` field of the
-      [K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps)
+      [K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
     instrument: updowncounter
     unit: "{pod}"
   - id: metric.k8s.statefulset.current_pods
@@ -221,7 +241,10 @@ groups:
     brief: "The number of replica pods created by the statefulset controller from the statefulset version indicated by currentRevision"
     note: |
       This metric aligns with the `currentReplicas` field of the
-      [K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps)
+      [K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
     instrument: updowncounter
     unit: "{pod}"
   - id: metric.k8s.statefulset.updated_pods
@@ -231,7 +254,10 @@ groups:
     brief: "Number of replica pods created by the statefulset controller from the statefulset version indicated by updateRevision"
     note: |
       This metric aligns with the `updatedReplicas` field of the
-      [K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps)
+      [K8s StatefulSetStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#statefulsetstatus-v1-apps).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.statefulset`](../resource/k8s.md#statefulset) resource.
     instrument: updowncounter
     unit: "{pod}"
 
@@ -241,6 +267,7 @@ groups:
     metric_name: k8s.hpa.desired_pods
     stability: experimental
     brief: "Desired number of replica pods managed by this horizontal pod autoscaler, as last calculated by the autoscaler"
+    # TODO: Add note for resource correlation once https://github.com/open-telemetry/semantic-conventions/issues/1656 is implemented
     note: |
       This metric aligns with the `desiredReplicas` field of the
       [K8s HorizontalPodAutoscalerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerstatus-v2-autoscaling)
@@ -251,6 +278,7 @@ groups:
     metric_name: k8s.hpa.current_pods
     stability: experimental
     brief: "Current number of replica pods managed by this horizontal pod autoscaler, as last seen by the autoscaler"
+    # TODO: Add note for resource correlation once https://github.com/open-telemetry/semantic-conventions/issues/1656 is implemented
     note: |
       This metric aligns with the `currentReplicas` field of the
       [K8s HorizontalPodAutoscalerStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerstatus-v2-autoscaling)
@@ -261,6 +289,7 @@ groups:
     metric_name: k8s.hpa.max_pods
     stability: experimental
     brief: "The upper limit for the number of replica pods to which the autoscaler can scale up"
+    # TODO: Add note for resource correlation once https://github.com/open-telemetry/semantic-conventions/issues/1656 is implemented
     note: |
       This metric aligns with the `maxReplicas` field of the
       [K8s HorizontalPodAutoscalerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerspec-v2-autoscaling)
@@ -271,6 +300,7 @@ groups:
     metric_name: k8s.hpa.min_pods
     stability: experimental
     brief: "The lower limit for the number of replica pods to which the autoscaler can scale down"
+    # TODO: Add note for resource correlation once https://github.com/open-telemetry/semantic-conventions/issues/1656 is implemented
     note: |
       This metric aligns with the `minReplicas` field of the
       [K8s HorizontalPodAutoscalerSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#horizontalpodautoscalerspec-v2-autoscaling)