[cicd] combine cicd.pipeline.run.active and queued metrics

distinguish them by the new cicd.pipeline.run.state attribute
open-telemetry · Jan 19, 2025 · 1d88f59 · 1d88f59
1 parent 13ca0f3
commit 1d88f59
Show file tree

Hide file tree

Showing 5 changed files with 47 additions and 39 deletions.
diff --git a/.chloggen/1600-cicd-metrics.yaml b/.chloggen/1600-cicd-metrics.yaml
@@ -22,6 +22,6 @@ issues: [1600]
 subtext: |
   Makes the following changes:
 
-  - Add metrics `cicd.pipeline.run.duration`, `cicd.pipeline.run.active`, `cicd.pipeline.run.time_in_queue`, `cicd.pipeline.run.queued`, `cicd.worker.count`,
+  - Add metrics `cicd.pipeline.run.duration`, `cicd.pipeline.run.active`, `cicd.pipeline.run.time_in_queue`, `cicd.worker.count`,
     `cicd.pipeline.run.errors` and `cicd.system.errors`.
-  - The CICD attributes `cicd.pipeline.result`, `cicd.system.component`, `cicd.worker.state` have been added to the registry.
+  - The CICD attributes `cicd.pipeline.run.state`, `cicd.pipeline.result`, `cicd.system.component`, `cicd.worker.state` have been added to the registry.
diff --git a/docs/attributes-registry/cicd.md b/docs/attributes-registry/cicd.md
@@ -15,6 +15,7 @@ This group describes attributes specific to pipelines within a Continuous Integr
 | <a id="cicd-pipeline-name" href="#cicd-pipeline-name">`cicd.pipeline.name`</a> | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="cicd-pipeline-result" href="#cicd-pipeline-result">`cicd.pipeline.result`</a> | string | The result of a pipeline run. | `success`; `failure`; `timeout`; `skipped` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="cicd-pipeline-run-id" href="#cicd-pipeline-run-id">`cicd.pipeline.run.id`</a> | string | The unique identifier of a pipeline run within a CI/CD system. | `120912` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="cicd-pipeline-run-state" href="#cicd-pipeline-run-state">`cicd.pipeline.run.state`</a> | string | The pipeline run goes through these states during its lifecycle. | `pending`; `executing`; `finalizing` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="cicd-pipeline-task-name" href="#cicd-pipeline-task-name">`cicd.pipeline.task.name`</a> | string | The human readable name of a task within a pipeline. Task here most closely aligns with a [computing process](https://wikipedia.org/wiki/Pipeline_(computing)) in a pipeline. Other terms for tasks include commands, steps, and procedures. | `Run GoLang Linter`; `Go Build`; `go-test`; `deploy_binary` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="cicd-pipeline-task-run-id" href="#cicd-pipeline-task-run-id">`cicd.pipeline.task.run.id`</a> | string | The unique identifier of a task run within a pipeline. | `12097` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="cicd-pipeline-task-run-url-full" href="#cicd-pipeline-task-run-url-full">`cicd.pipeline.task.run.url.full`</a> | string | The [URL](https://wikipedia.org/wiki/URL) of the pipeline run providing the complete address in order to locate and identify the pipeline run. | `https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
@@ -37,6 +38,16 @@ This group describes attributes specific to pipelines within a Continuous Integr
 
 ---
 
+`cicd.pipeline.run.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value  | Description | Stability |
+|---|---|---|
+| `executing` | The executing state spans the execution of any run tasks (eg. build, test). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `finalizing` | The finalizing state spans from when the run has finished executing (eg. cleanup of run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `pending` | The run pending state spans from the event triggering the pipeline run until the execution of the run starts (eg. time spent in a queue, provisioning agents, creating run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+---
+
 `cicd.pipeline.task.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
 | Value  | Description | Stability |

diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md
@@ -14,7 +14,6 @@ linkTitle: CICD metrics
   - [Metric: `cicd.pipeline.run.duration`](#metric-cicdpipelinerunduration)
   - [Metric: `cicd.pipeline.run.active`](#metric-cicdpipelinerunactive)
   - [Metric: `cicd.pipeline.run.time_in_queue`](#metric-cicdpipelineruntime_in_queue)
-  - [Metric: `cicd.pipeline.run.queued`](#metric-cicdpipelinerunqueued)
   - [Metric: `cicd.worker.count`](#metric-cicdworkercount)
   - [Metric: `cicd.pipeline.run.errors`](#metric-cicdpipelinerunerrors)
   - [Metric: `cicd.system.errors`](#metric-cicdsystemerrors)
@@ -118,46 +117,33 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `cicd.pipeline.run.active` | UpDownCounter | `{run}` | The number of pipeline runs currently executing. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cicd.pipeline.run.active` | UpDownCounter | `{run}` | The number of pipeline runs currently active in the system by state. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
 | [`cicd.pipeline.name`](/docs/attributes-registry/cicd.md) | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cicd.pipeline.run.state`](/docs/attributes-registry/cicd.md) | string | The pipeline run goes through these states during its lifecycle. | `pending`; `executing`; `finalizing` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-<!-- END AUTOGENERATED TEXT -->
-<!-- endsemconv -->
-
-### Metric: `cicd.pipeline.run.time_in_queue`
-
-This metric is [recommended][MetricRecommended].
-
-<!-- semconv metric.cicd.pipeline.run.time_in_queue -->
-<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
-<!-- see templates/registry/markdown/snippet.md.j2 -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-capture -->
-<!-- markdownlint-disable -->
+---
 
-| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
-| -------- | --------------- | ----------- | -------------- | --------- |
-| `cicd.pipeline.run.time_in_queue` | Histogram | `s` | The duration a pipeline run takes from being triggered to the start of execution. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+`cicd.pipeline.run.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
 
-| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
-|---|---|---|---|---|---|
-| [`cicd.pipeline.name`](/docs/attributes-registry/cicd.md) | string | The human readable name of the pipeline within a CI/CD system. | `Build and Test`; `Lint`; `Deploy Go Project`; `deploy_to_environment` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| Value  | Description | Stability |
+|---|---|---|
+| `executing` | The executing state spans the execution of any run tasks (eg. build, test). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `finalizing` | The finalizing state spans from when the run has finished executing (eg. cleanup of run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `pending` | The run pending state spans from the event triggering the pipeline run until the execution of the run starts (eg. time spent in a queue, provisioning agents, creating run resources). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `cicd.pipeline.run.queued`
+### Metric: `cicd.pipeline.run.time_in_queue`
 
 This metric is [recommended][MetricRecommended].
 
-<!-- semconv metric.cicd.pipeline.run.queued -->
+<!-- semconv metric.cicd.pipeline.run.time_in_queue -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
@@ -166,7 +152,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `cicd.pipeline.run.queued` | UpDownCounter | `{run}` | The number of pipeline runs waiting for their start of execution. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `cicd.pipeline.run.time_in_queue` | Histogram | `s` | The duration a pipeline run takes from being triggered to the start of execution. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|

diff --git a/model/cicd/metrics.yaml b/model/cicd/metrics.yaml
@@ -17,13 +17,15 @@ groups:
   - id: metric.cicd.pipeline.run.active
     type: metric
     metric_name: cicd.pipeline.run.active
-    brief: 'The number of pipeline runs currently executing.'
+    brief: 'The number of pipeline runs currently active in the system by state.'
     instrument: updowncounter
     unit: "{run}"
     stability: experimental
     attributes:
       - ref: cicd.pipeline.name
         requirement_level: required
+      - ref: cicd.pipeline.run.state
+        requirement_level: required
   - id: metric.cicd.pipeline.run.time_in_queue
     type: metric
     metric_name: cicd.pipeline.run.time_in_queue
@@ -34,16 +36,6 @@ groups:
     attributes:
       - ref: cicd.pipeline.name
         requirement_level: recommended
-  - id: metric.cicd.pipeline.run.queued
-    type: metric
-    metric_name: cicd.pipeline.run.queued
-    brief: 'The number of pipeline runs waiting for their start of execution.'
-    instrument: updowncounter
-    unit: "{run}"
-    stability: experimental
-    attributes:
-      - ref: cicd.pipeline.name
-        requirement_level: recommended
   - id: metric.cicd.worker.count
     type: metric
     metric_name: cicd.worker.count

diff --git a/model/cicd/registry.yaml b/model/cicd/registry.yaml
@@ -31,6 +31,25 @@ groups:
         brief: >
           The unique identifier of a pipeline run within a CI/CD system.
         examples: ["120912"]
+      - id: cicd.pipeline.run.state
+        type:
+          members:
+            - id: pending
+              value: pending
+              brief: The run pending state spans from the event triggering the pipeline run until the execution of the run starts (eg. time spent in a queue, provisioning agents, creating run resources).
+              stability: experimental
+            - id: executing
+              value: executing
+              brief: The executing state spans the execution of any run tasks (eg. build, test).
+              stability: experimental
+            - id: finalizing
+              value: finalizing
+              brief: The finalizing state spans from when the run has finished executing (eg. cleanup of run resources).
+              stability: experimental
+        stability: experimental
+        brief: >
+          The pipeline run goes through these states during its lifecycle.
+        examples: ["pending", "executing", "finalizing"]
       - id: cicd.pipeline.task.name
         type: string
         stability: experimental