diff --git a/.chloggen/1600-cicd-metrics.yaml b/.chloggen/1600-cicd-metrics.yaml index 434417778f..b98ea1b741 100644 --- 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 index 8daa832336..07f51b2a4c 100644 --- 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 | `cicd.pipeline.name` | 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) | | `cicd.pipeline.result` | string | The result of a pipeline run. | `success`; `failure`; `timeout`; `skipped` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.run.id` | string | The unique identifier of a pipeline run within a CI/CD system. | `120912` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `cicd.pipeline.run.state` | string | The pipeline run goes through these states during its lifecycle. | `pending`; `executing`; `finalizing` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.task.name` | 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) | | `cicd.pipeline.task.run.id` | string | The unique identifier of a task run within a pipeline. | `12097` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `cicd.pipeline.task.run.url.full` | 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 index e7428888fd..4852da9f6d 100644 --- 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) | - - - - - -### Metric: `cicd.pipeline.run.time_in_queue` - -This metric is [recommended][MetricRecommended]. - - - - - - - +--- -| 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) | -### Metric: `cicd.pipeline.run.queued` +### Metric: `cicd.pipeline.run.time_in_queue` This metric is [recommended][MetricRecommended]. - + @@ -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 index 565e1fa99a..2a5a1ddffa 100644 --- 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 index 244cbf57cc..c1afc8042a 100644 --- 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