Add notes about resource correlation

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

Hide file tree

Showing 2 changed files with 48 additions and 12 deletions.
diff --git a/docs/system/k8s-metrics.md b/docs/system/k8s-metrics.md
@@ -345,7 +345,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.job.active_pods` | UpDownCounter | `{pod}` | The number of pending and actively running pods for a job [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `active` field of the
-[K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch)
+[K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.job`](../resource/k8s.md#job) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -368,7 +371,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.job.failed_pods` | UpDownCounter | `{pod}` | The number of pods which reached phase Failed for a job [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `failed` field of the
-[K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch)
+[K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.job`](../resource/k8s.md#job) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -391,7 +397,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.job.successful_pods` | UpDownCounter | `{pod}` | The number of pods which reached phase Succeeded for a job [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `succeeded` field of the
-[K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch)
+[K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.job`](../resource/k8s.md#job) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -414,7 +423,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.job.desired_successful_pods` | UpDownCounter | `{pod}` | The desired number of successfully finished pods the job should be run with [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `completions` field of the
-[K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch)
+[K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.job`](../resource/k8s.md#job) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -437,7 +449,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.job.max_parallel_pods` | UpDownCounter | `{pod}` | The max desired number of pods the job should run at any given time [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `parallelism` field of the
-[K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch
+[K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch.
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.job`](../resource/k8s.md#job) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
@@ -460,7 +475,10 @@ This metric is [recommended][MetricRecommended].
 | `k8s.cronjob.active_jobs` | UpDownCounter | `{job}` | The number of actively running jobs for a cronjob [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1]:** This metric aligns with the `active` field of the
-[K8s CronJobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#cronjobstatus-v1-batch)
+[K8s CronJobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#cronjobstatus-v1-batch).
+
+This metric SHOULD, at a minimum, be reported against a
+[`k8s.cronjob`](../resource/k8s.md#cronjob) resource.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->

diff --git a/model/k8s/metrics.yaml b/model/k8s/metrics.yaml
@@ -137,7 +137,10 @@ groups:
     unit: "{pod}"
     note: |
       This metric aligns with the `active` field of the
-      [K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch)
+      [K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.job`](../resource/k8s.md#job) resource.
   - id: metric.k8s.job.failed_pods
     type: metric
     metric_name: k8s.job.failed_pods
@@ -147,7 +150,10 @@ groups:
     unit: "{pod}"
     note: |
       This metric aligns with the `failed` field of the
-      [K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch)
+      [K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.job`](../resource/k8s.md#job) resource.
   - id: metric.k8s.job.successful_pods
     type: metric
     metric_name: k8s.job.successful_pods
@@ -157,7 +163,10 @@ groups:
     unit: "{pod}"
     note: |
       This metric aligns with the `succeeded` field of the
-      [K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch)
+      [K8s JobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobstatus-v1-batch).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.job`](../resource/k8s.md#job) resource.
   - id: metric.k8s.job.desired_successful_pods
     type: metric
     metric_name: k8s.job.desired_successful_pods
@@ -167,7 +176,10 @@ groups:
     unit: "{pod}"
     note: |
       This metric aligns with the `completions` field of the
-      [K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch)
+      [K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.job`](../resource/k8s.md#job) resource.
   - id: metric.k8s.job.max_parallel_pods
     type: metric
     metric_name: k8s.job.max_parallel_pods
@@ -177,7 +189,10 @@ groups:
     unit: "{pod}"
     note: |
       This metric aligns with the `parallelism` field of the
-      [K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch
+      [K8s JobSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#jobspec-v1-batch.
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.job`](../resource/k8s.md#job) resource.
 
   # k8s.job.* metrics
   - id: metric.k8s.cronjob.active_jobs
@@ -189,4 +204,7 @@ groups:
     unit: "{job}"
     note: |
       This metric aligns with the `active` field of the
-      [K8s CronJobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#cronjobstatus-v1-batch)
+      [K8s CronJobStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.30/#cronjobstatus-v1-batch).
+
+      This metric SHOULD, at a minimum, be reported against a
+      [`k8s.cronjob`](../resource/k8s.md#cronjob) resource.