open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add CICD metrics (#1681) 

Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
This commit is contained in:
Christophe Kamphaus 2025-01-23 11:29:42 +01:00 committed by GitHub
parent b0f39690ab
commit 98244d9c1a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 498 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
.chloggen/1600-cicd-metrics.yaml Normal file
View File

@ -0,0 +1,27 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: enhancement
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: cicd
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Add CICD metrics
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
issues: [1600]
# (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: |
Makes the following changes:
- Add metrics `cicd.pipeline.run.duration`, `cicd.pipeline.run.active`, `cicd.worker.count`,
`cicd.pipeline.run.errors` and `cicd.system.errors`.
- The CICD attributes `cicd.pipeline.run.state`, `cicd.pipeline.result`, `cicd.system.component`, `cicd.worker.state` have been added to the registry.

3
.vscode/settings.json vendored
View File

@ -14,5 +14,6 @@
"model/**/*.yaml" "model/**/*.yaml"
] ]
}, },
"json.schemaDownload.enable": true "json.schemaDownload.enable": true,
"markdown.extension.toc.levels": "2..6"
} }

39
docs/attributes-registry/cicd.md
View File

@ -13,11 +13,38 @@ This group describes attributes specific to pipelines within a Continuous Integr
| Attribute | Type | Description | Examples | Stability | | Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---| |---|---|---|---|---|
| <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-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-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-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-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) | | <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) |
| <a id="cicd-pipeline-task-type" href="#cicd-pipeline-task-type">`cicd.pipeline.task.type`</a> | string | The type of the task within a pipeline. | `build`; `test`; `deploy` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | <a id="cicd-pipeline-task-type" href="#cicd-pipeline-task-type">`cicd.pipeline.task.type`</a> | string | The type of the task within a pipeline. | `build`; `test`; `deploy` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="cicd-system-component" href="#cicd-system-component">`cicd.system.component`</a> | string | The name of a component of the CICD system. | `controller`; `scheduler`; `agent` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="cicd-worker-state" href="#cicd-worker-state">`cicd.worker.state`</a> | string | The state of a CICD worker / agent. | `idle`; `busy`; `down` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
---
`cicd.pipeline.result` 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 |
|---|---|---|
| `cancellation` | The pipeline run was cancelled, eg. by a user manually cancelling the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `error` | The pipeline run failed due to an error in the CICD system, eg. due to the worker being killed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `failure` | The pipeline run did not finish successfully, eg. due to a compile error or a failing test. Such failures are usually detected by non-zero exit codes of the tools executed in the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `skip` | The pipeline run was skipped, eg. due to a precondition not being met. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `success` | The pipeline run finished successfully. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `timeout` | A timeout caused the pipeline run to be interrupted. | ![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.
| 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) |
--- ---
@ -28,3 +55,15 @@ This group describes attributes specific to pipelines within a Continuous Integr
| `build` | build | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `build` | build | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `deploy` | deploy | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `deploy` | deploy | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `test` | test | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `test` | test | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
---
`cicd.worker.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 |
|---|---|---|
| `available` | The worker is not performing work for the CICD system. It is available to the CICD system to perform work on (online / idle). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `busy` | The worker is performing work for the CICD system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `offline` | The worker is not available to the CICD system (disconnected / down). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** Pipelines might have conditions on which workers they are able to run so not every worker might be available to every pipeline.

275
docs/cicd/cicd-metrics.md
View File

@ -10,6 +10,12 @@ linkTitle: CICD metrics
<!-- toc --> <!-- toc -->
- [CICD Metrics](#cicd-metrics)
- [Metric: `cicd.pipeline.run.duration`](#metric-cicdpipelinerunduration)
- [Metric: `cicd.pipeline.run.active`](#metric-cicdpipelinerunactive)
- [Metric: `cicd.worker.count`](#metric-cicdworkercount)
- [Metric: `cicd.pipeline.run.errors`](#metric-cicdpipelinerunerrors)
- [Metric: `cicd.system.errors`](#metric-cicdsystemerrors)
- [VCS Metrics](#vcs-metrics) - [VCS Metrics](#vcs-metrics)
- [Metric: `vcs.change.count`](#metric-vcschangecount) - [Metric: `vcs.change.count`](#metric-vcschangecount)
- [Metric: `vcs.change.duration`](#metric-vcschangeduration) - [Metric: `vcs.change.duration`](#metric-vcschangeduration)
@ -23,6 +29,275 @@ linkTitle: CICD metrics
<!-- tocstop --> <!-- tocstop -->
## CICD Metrics
The conventions described in this section are specific to Continuous Integration / Continuous Deployment (CICD) systems.
**Disclaimer:** These are initial CICD metrics and attributes
but more may be added in the future.
### Metric: `cicd.pipeline.run.duration`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.cicd.pipeline.run.duration -->
<!-- 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.duration` | Histogram | `s` | Duration of a pipeline run grouped by pipeline, state and result. | ![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) |
| [`cicd.pipeline.result`](/docs/attributes-registry/cicd.md) | string | The result of a pipeline run. | `success`; `failure`; `timeout`; `skipped` | `Conditionally Required` [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` If and only if the pipeline run failed. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
**[1] `cicd.pipeline.result`:** If and only if the pipeline run result has been set during that state.
**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low.
Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time when no
additional filters are applied.
If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
---
`cicd.pipeline.result` 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 |
|---|---|---|
| `cancellation` | The pipeline run was cancelled, eg. by a user manually cancelling the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `error` | The pipeline run failed due to an error in the CICD system, eg. due to the worker being killed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `failure` | The pipeline run did not finish successfully, eg. due to a compile error or a failing test. Such failures are usually detected by non-zero exit codes of the tools executed in the pipeline run. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `skip` | The pipeline run was skipped, eg. due to a precondition not being met. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `success` | The pipeline run finished successfully. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `timeout` | A timeout caused the pipeline run to be interrupted. | ![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.
| 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) |
---
`error.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 |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `cicd.pipeline.run.active`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.cicd.pipeline.run.active -->
<!-- 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.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) |
---
`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) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `cicd.worker.count`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.cicd.worker.count -->
<!-- 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.worker.count` | UpDownCounter | `{count}` | The number of workers on the CICD 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.worker.state`](/docs/attributes-registry/cicd.md) | string | The state of a CICD worker / agent. | `idle`; `busy`; `down` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
---
`cicd.worker.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 |
|---|---|---|
| `available` | The worker is not performing work for the CICD system. It is available to the CICD system to perform work on (online / idle). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `busy` | The worker is performing work for the CICD system. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| `offline` | The worker is not available to the CICD system (disconnected / down). | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** Pipelines might have conditions on which workers they are able to run so not every worker might be available to every pipeline.
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `cicd.pipeline.run.errors`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.cicd.pipeline.run.errors -->
<!-- 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.errors` | Counter | `{error}` | The number of errors encountered in pipeline runs (eg. compile, test failures). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** There might be errors in a pipeline run that are non fatal (eg. they are suppressed) or in a parallel stage multiple stages could have a fatal error.
This means that this error count might not be the same as the count of metric `cicd.pipeline.run.duration` with run result `failure`.
| 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) |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low.
Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time when no
additional filters are applied.
If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
---
`error.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 |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `cicd.system.errors`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.cicd.system.errors -->
<!-- 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.system.errors` | Counter | `{error}` | The number of errors in a component of the CICD system (eg. controller, scheduler, agent). [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1]:** Errors in pipeline run execution are explicitly excluded. Ie a test failure is not counted in this metric.
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`cicd.system.component`](/docs/attributes-registry/cicd.md) | string | The name of a component of the CICD system. | `controller`; `scheduler`; `agent` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Required` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
**[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality.
When `error.type` is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
Instrumentations SHOULD document the list of errors they report.
The cardinality of `error.type` within one instrumentation library SHOULD be low.
Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for `error.type` to have high cardinality at query time when no
additional filters are applied.
If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
it's RECOMMENDED to:
- Use a domain-specific attribute
- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
---
`error.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 |
|---|---|---|
| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
## VCS Metrics ## VCS Metrics
The conventions described in this section are specific to Version Control Systems. The conventions described in this section are specific to Version Control Systems.

69
model/cicd/metrics.yaml Normal file
View File

@ -0,0 +1,69 @@
groups:
- id: metric.cicd.pipeline.run.duration
type: metric
metric_name: cicd.pipeline.run.duration
brief: 'Duration of a pipeline run grouped by pipeline, state and result.'
instrument: histogram
unit: "s"
stability: experimental
attributes:
- ref: cicd.pipeline.name
requirement_level: required
- ref: cicd.pipeline.run.state
requirement_level: required
- ref: cicd.pipeline.result
requirement_level:
conditionally_required: If and only if the pipeline run result has been set during that state.
- ref: error.type
requirement_level:
conditionally_required: If and only if the pipeline run failed.
- id: metric.cicd.pipeline.run.active
type: metric
metric_name: cicd.pipeline.run.active
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.worker.count
type: metric
metric_name: cicd.worker.count
brief: 'The number of workers on the CICD system by state.'
instrument: updowncounter
unit: "{count}"
stability: experimental
attributes:
- ref: cicd.worker.state
requirement_level: required
- id: metric.cicd.pipeline.run.errors
type: metric
metric_name: cicd.pipeline.run.errors
brief: 'The number of errors encountered in pipeline runs (eg. compile, test failures).'
note: |
There might be errors in a pipeline run that are non fatal (eg. they are suppressed) or in a parallel stage multiple stages could have a fatal error.
This means that this error count might not be the same as the count of metric `cicd.pipeline.run.duration` with run result `failure`.
instrument: counter
unit: "{error}"
stability: experimental
attributes:
- ref: cicd.pipeline.name
requirement_level: required
- ref: error.type
requirement_level: required
- id: metric.cicd.system.errors
type: metric
metric_name: cicd.system.errors
brief: 'The number of errors in a component of the CICD system (eg. controller, scheduler, agent).'
note: 'Errors in pipeline run execution are explicitly excluded. Ie a test failure is not counted in this metric.'
instrument: counter
unit: "{error}"
stability: experimental
attributes:
- ref: cicd.system.component
requirement_level: required
- ref: error.type
requirement_level: required

86
model/cicd/registry.yaml
View File

@ -31,6 +31,26 @@ groups:
brief: > brief: >
The unique identifier of a pipeline run within a CI/CD system. The unique identifier of a pipeline run within a CI/CD system.
examples: ["120912"] 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 - id: cicd.pipeline.task.name
type: string type: string
stability: experimental stability: experimental
@ -75,3 +95,69 @@ groups:
brief: > brief: >
The type of the task within a pipeline. The type of the task within a pipeline.
examples: ["build", "test", "deploy"] examples: ["build", "test", "deploy"]
- id: cicd.pipeline.result
type:
members:
- id: success
value: success
brief: "The pipeline run finished successfully."
stability: experimental
- id: failure
value: failure
brief: >-
The pipeline run did not finish successfully, eg. due to a compile error or a failing test.
Such failures are usually detected by non-zero exit codes of the tools executed in the pipeline run.
stability: experimental
- id: error
value: error
brief: >-
The pipeline run failed due to an error in the CICD system, eg. due to the worker being killed.
stability: experimental
- id: timeout
value: timeout
brief: "A timeout caused the pipeline run to be interrupted."
stability: experimental
- id: cancellation
value: cancellation
brief: "The pipeline run was cancelled, eg. by a user manually cancelling the pipeline run."
stability: experimental
- id: skip
value: skip
brief: "The pipeline run was skipped, eg. due to a precondition not being met."
stability: experimental
stability: experimental
brief: >
The result of a pipeline run.
examples: ["success", "failure", "timeout", "skipped"]
- id: cicd.worker.state
type:
members:
- id: available
value: available
brief: >-
The worker is not performing work for the CICD system.
It is available to the CICD system to perform work on (online / idle).
note: "Pipelines might have conditions on which workers they are able to run so not every worker might be available to every pipeline."
stability: experimental
- id: busy
value: busy
brief: "The worker is performing work for the CICD system."
stability: experimental
- id: offline
value: offline
brief: "The worker is not available to the CICD system (disconnected / down)."
stability: experimental
stability: experimental
brief: >
The state of a CICD worker / agent.
examples: ["idle", "busy", "down"]
- id: cicd.system.component
type: string
stability: experimental
brief: The name of a component of the CICD system.
examples:
[
"controller",
"scheduler",
"agent",
]