diff --git a/.chloggen/cicd-reg-attr.yaml b/.chloggen/cicd-reg-attr.yaml new file mode 100755 index 0000000000..a50fe72f31 --- /dev/null +++ b/.chloggen/cicd-reg-attr.yaml @@ -0,0 +1,24 @@ +# 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: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: cicd, deployment, artifact, test, vcs + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Adds CICD common attributes to the registry. + +# 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: [915, 832, 833] + +# (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: | + - CICD common attributes have been added to the registry. + - `deployment.environment` has been deprecated and moved to `deployment.environment.name`. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 8f68d4cde4..de593477f3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -87,3 +87,11 @@ /model/metrics/process-metrics.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers /model/resource/process.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers /model/network.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers + +# CICD semantic conventions approvers +/model/registry/artifact.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/cicd.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/code.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/deployment.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/test.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers +/model/registry/vcs.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index d1c9ea3014..753cd1d694 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -20,9 +20,11 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:artifact - area:aspnetcore - area:aws - area:browser + - area:cicd - area:client - area:cloud - area:cloudevents @@ -68,12 +70,14 @@ body: - area:source - area:system - area:telemetry + - area:test - area:thread - area:tls - area:url - area:user-agent - area:user - area:v8js + - area:vcs - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index cfd3172826..379bfe43d2 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -13,9 +13,11 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:artifact - area:aspnetcore - area:aws - area:browser + - area:cicd - area:client - area:cloud - area:cloudevents @@ -61,12 +63,14 @@ body: - area:source - area:system - area:telemetry + - area:test - area:thread - area:tls - area:url - area:user-agent - area:user - area:v8js + - area:vcs - area:webengine # End semconv area list - type: textarea diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 05a82fba0a..7df4c07895 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -22,9 +22,11 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:artifact - area:aspnetcore - area:aws - area:browser + - area:cicd - area:client - area:cloud - area:cloudevents @@ -70,12 +72,14 @@ body: - area:source - area:system - area:telemetry + - area:test - area:thread - area:tls - area:url - area:user-agent - area:user - area:v8js + - area:vcs - area:webengine # End semconv area list - type: textarea diff --git a/.gitignore b/.gitignore index 46abe54e81..8e0d07a07f 100644 --- a/.gitignore +++ b/.gitignore @@ -34,4 +34,7 @@ package-lock.json .vscode # Visual Studio -.vs/ \ No newline at end of file +.vs/ + +# Python +venv diff --git a/.markdown_link_check_config.json b/.markdown_link_check_config.json index d16ec85009..6d5312790a 100644 --- a/.markdown_link_check_config.json +++ b/.markdown_link_check_config.json @@ -4,7 +4,7 @@ "pattern": "^https://github\\.com/open-telemetry/opentelemetry-specification/(issues|pull)" }, { - "pattern": "^https://github\\.com/open-telemetry/semantic-conventions/(issues|pull)" + "pattern": "^https://github\\.com/open-telemetry/semantic-conventions/(issues|pull|actions)" } ], "replacementPatterns": [ diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index facabc6743..af4e2c4d5e 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -32,9 +32,11 @@ All registered attributes are listed by namespace in this registry. Currently, the following namespaces exist: - [Android](android.md) +- [Artifact](artifact.md) - [Aspnetcore](aspnetcore.md) - [AWS](aws.md) - [Browser](browser.md) +- [CICD](cicd.md) - [Client](client.md) - [Cloud](cloud.md) - [CloudEvents](cloudevents.md) @@ -82,12 +84,14 @@ Currently, the following namespaces exist: - [Source](source.md) - [System](system.md) - [Telemetry](telemetry.md) +- [Test](test.md) - [Thread](thread.md) - [TLS](tls.md) - [URL](url.md) - [User](user.md) - [User Agent](user-agent.md) - [V8js](v8js.md) +- [VCS](vcs.md) - [Webengine](webengine.md) [developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers diff --git a/docs/attributes-registry/artifact.md b/docs/attributes-registry/artifact.md new file mode 100644 index 0000000000..fe6aa28a93 --- /dev/null +++ b/docs/attributes-registry/artifact.md @@ -0,0 +1,35 @@ + + + + + +# Artifact + +## Artifact Attributes + +This group describes attributes specific to artifacts. Artifacts are files or other immutable objects that are intended for distribution. This definition aligns directly with the [SLSA](https://slsa.dev/spec/v1.0/terminology#package-model) package model. + +| Attribute | Type | Description | Examples | Stability | +| ------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `artifact.attestation.filename` | string | The provenance filename of the built attestation which directly relates to the build artifact filename. This filename SHOULD accompany the artifact at publish time. See the [SLSA Relationship](https://slsa.dev/spec/v1.0/distributing-provenance#relationship-between-artifacts-and-attestations) specification for more information. | `golang-binary-amd64-v0.1.0.attestation`; `docker-image-amd64-v0.1.0.intoto.json1`; `release-1.tar.gz.attestation`; `file-name-package.tar.gz.intoto.json1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.attestation.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the built attestation. Some envelopes in the software attestation space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). | `1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.attestation.id` | string | The id of the build [software attestation](https://slsa.dev/attestation-model). | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.filename` | string | The human readable file name of the artifact, typically generated during build and release processes. Often includes the package name and version in the file name. [1] | `golang-binary-amd64-v0.1.0`; `docker-image-amd64-v0.1.0`; `release-1.tar.gz`; `file-name-package.tar.gz` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.hash` | string | The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), often found in checksum.txt on a release of the artifact and used to verify package integrity. [2] | `9ff4c52759e2c4ac70b7d517bc7fcdc1cda631ca0045271ddd1b192544f8a3e9` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.purl` | string | The [Package URL](https://github.com/package-url/purl-spec) of the [package artifact](https://slsa.dev/spec/v1.0/terminology#package-model) provides a standard way to identify and locate the packaged artifact. | `pkg:github/package-url/purl-spec@1209109710924`; `pkg:npm/foo@12.12.3` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `artifact.version` | string | The version of the artifact. | `v0.1.0`; `1.2.1`; `122691-build` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This file name can also act as the [Package Name](https://slsa.dev/spec/v1.0/terminology#package-model) +in cases where the package ecosystem maps accordingly. +Additionally, the artifact [can be published](https://slsa.dev/spec/v1.0/terminology#software-supply-chain) +for others, but that is not a guarantee. + +**[2]:** The specific algorithm used to create the cryptographic hash value is +not defined. In situations where an artifact has multiple +cryptographic hashes, it is up to the implementer to choose which +hash value to set here; this should be the most secure hash algorithm +that is suitable for the situation and consistent with the +corresponding attestation. The implementer can then provide the other +hash values through an additional set of attribute extensions as they +deem necessary. diff --git a/docs/attributes-registry/cicd.md b/docs/attributes-registry/cicd.md new file mode 100644 index 0000000000..858bf01b96 --- /dev/null +++ b/docs/attributes-registry/cicd.md @@ -0,0 +1,28 @@ + + + + + +# CICD + +## CICD Pipeline Attributes + +This group describes attributes specific to pipelines within a Continuous Integration and Continuous Deployment (CI/CD) system. A [pipeline]() in this case is a series of steps that are performed in order to deliver a new version of software. This aligns with the [Britannica](https://www.britannica.com/dictionary/pipeline) definition of a pipeline where a **pipeline** is the system for developing and producing something. In the context of CI/CD, a pipeline produces or delivers software. + +| Attribute | Type | Description | Examples | Stability | +| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `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.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.task.name` | string | The human readable name of a task within a pipeline. Task here most closely aligns with a [computing process]() 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://en.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) | +| `cicd.pipeline.task.type` | string | The type of the task within a pipeline. | `build`; `test`; `deploy` | ![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 | +| -------- | ----------- | ---------------------------------------------------------------- | +| `build` | build | ![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) | diff --git a/docs/attributes-registry/deployment.md b/docs/attributes-registry/deployment.md index 97c68f3ebf..85fd31f339 100644 --- a/docs/attributes-registry/deployment.md +++ b/docs/attributes-registry/deployment.md @@ -6,18 +6,39 @@ # Deployment +- [Deployment Attributes](#deployment-attributes) +- [Deployment Deprecated Attributes](#deployment-deprecated-attributes) + ## Deployment Attributes This document defines attributes for software deployments. -| Attribute | Type | Description | Examples | Stability | -| ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | ---------------------------------------------------------------- | -| `deployment.environment` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ---------------------------------------------------------------- | +| `deployment.environment.name` | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deployment.id` | string | The id of the deployment. | `1208` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deployment.name` | string | The name of the deployment. | `deploy my app`; `deploy-frontend` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `deployment.status` | string | The status of the deployment. | `failed`; `succeeded` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through +**[1]:** `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. This implies that resources carrying the following attribute combinations MUST be considered to be identifying the same service: -- `service.name=frontend`, `deployment.environment=production` -- `service.name=frontend`, `deployment.environment=staging`. +- `service.name=frontend`, `deployment.environment.name=production` +- `service.name=frontend`, `deployment.environment.name=staging`. + +`deployment.status` 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 | +| ----------- | ----------- | ---------------------------------------------------------------- | +| `failed` | failed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `succeeded` | succeeded | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## Deployment Deprecated Attributes + +"Describes deprecated deployment attributes." + +| Attribute | Type | Description | Examples | Stability | +| ------------------------ | ------ | -------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `deployment.environment` | string | 'Deprecated, use `deployment.environment.name` instead.' | `staging`; `production` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `deployment.environment.name` instead. | diff --git a/docs/attributes-registry/test.md b/docs/attributes-registry/test.md new file mode 100644 index 0000000000..c8ad68977b --- /dev/null +++ b/docs/attributes-registry/test.md @@ -0,0 +1,36 @@ + + + + + +# Test + +## Test Attributes + +This group describes attributes specific to [software tests](https://en.wikipedia.org/wiki/Software_testing). + +| Attribute | Type | Description | Examples | Stability | +| ------------------------- | ------ | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `test.case.name` | string | The fully qualified human readable name of the [test case](https://en.wikipedia.org/wiki/Test_case). | `org.example.TestCase1.test1`; `example/tests/TestCase1.test1`; `ExampleTestCase1_test1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test.case.result.status` | string | The status of the actual test case result from test execution. | `pass`; `fail` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test.suite.name` | string | The human readable name of a [test suite](https://en.wikipedia.org/wiki/Test_suite). | `TestSuite1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `test.suite.run.status` | string | The status of the test suite run. | `success`; `failure`; `skipped`; `aborted`; `timed_out`; `in_progress` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`test.case.result.status` 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 | +| ------ | ----------- | ---------------------------------------------------------------- | +| `fail` | fail | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `pass` | pass | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`test.suite.run.status` 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 | +| ------------- | ----------- | ---------------------------------------------------------------- | +| `aborted` | aborted | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `failure` | failure | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `in_progress` | in_progress | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `skipped` | skipped | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `success` | success | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `timed_out` | timed_out | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md new file mode 100644 index 0000000000..0e11f9b2bf --- /dev/null +++ b/docs/attributes-registry/vcs.md @@ -0,0 +1,37 @@ + + + + + +# VCS + +## VCS Repository Attributes + +This group defines the attributes for [Version Control Systems (VCS)](https://en.wikipedia.org/wiki/Version_control). + +| Attribute | Type | Description | Examples | Stability | +| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `vcs.repository.change.id` | string | The ID of the change (pull request/merge request) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.change.title` | string | The human readable title of the change (pull request/merge request). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.ref.name` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.ref.revision` | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [1] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.ref.type` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.url.full` | string | The [URL](https://en.wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a +[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +it is identical to the `ref.name`, it SHOULD still be included. It is +up to the implementer to decide which value to set as the revision +based on the VCS system and situational context. + +`vcs.repository.ref.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 | +| -------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | diff --git a/docs/resource/deployment-environment.md b/docs/resource/deployment-environment.md index 091ad8dba5..72cb250024 100644 --- a/docs/resource/deployment-environment.md +++ b/docs/resource/deployment-environment.md @@ -15,15 +15,15 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`deployment.environment`](/docs/attributes-registry/deployment.md) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`deployment.environment.name`](/docs/attributes-registry/deployment.md) | string | Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). [1] | `staging`; `production` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** `deployment.environment` does not affect the uniqueness constraints defined through +**[1]:** `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. This implies that resources carrying the following attribute combinations MUST be considered to be identifying the same service: -* `service.name=frontend`, `deployment.environment=production` -* `service.name=frontend`, `deployment.environment=staging`. +* `service.name=frontend`, `deployment.environment.name=production` +* `service.name=frontend`, `deployment.environment.name=staging`. diff --git a/model/registry/artifact.yaml b/model/registry/artifact.yaml new file mode 100644 index 0000000000..9bed81bbb1 --- /dev/null +++ b/model/registry/artifact.yaml @@ -0,0 +1,97 @@ +groups: + - id: registry.artifact + prefix: artifact + type: attribute_group + brief: > + This group describes attributes specific to artifacts. Artifacts are + files or other immutable objects that are intended for distribution. This + definition aligns directly with the + [SLSA](https://slsa.dev/spec/v1.0/terminology#package-model) package + model. + attributes: + - id: filename + type: string + stability: experimental + brief: > + The human readable file name of the artifact, typically generated + during build and release processes. Often includes the package name + and version in the file name. + note: | + This file name can also act as the [Package Name](https://slsa.dev/spec/v1.0/terminology#package-model) + in cases where the package ecosystem maps accordingly. + Additionally, the artifact [can be published](https://slsa.dev/spec/v1.0/terminology#software-supply-chain) + for others, but that is not a guarantee. + examples: + [ + "golang-binary-amd64-v0.1.0", + "docker-image-amd64-v0.1.0", + "release-1.tar.gz", + "file-name-package.tar.gz", + ] + - id: version + type: string + stability: experimental + brief: > + The version of the artifact. + examples: ["v0.1.0", "1.2.1", "122691-build"] + - id: purl + type: string + stability: experimental + brief: > + The [Package URL](https://github.com/package-url/purl-spec) of the + [package artifact](https://slsa.dev/spec/v1.0/terminology#package-model) + provides a standard way to identify and locate the packaged artifact. + examples: + [ + "pkg:github/package-url/purl-spec@1209109710924", + "pkg:npm/foo@12.12.3", + ] + - id: hash + type: string + stability: experimental + brief: > + The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + often found in checksum.txt on a release of the artifact and used to + verify package integrity. + note: | + The specific algorithm used to create the cryptographic hash value is + not defined. In situations where an artifact has multiple + cryptographic hashes, it is up to the implementer to choose which + hash value to set here; this should be the most secure hash algorithm + that is suitable for the situation and consistent with the + corresponding attestation. The implementer can then provide the other + hash values through an additional set of attribute extensions as they + deem necessary. + examples: + ["9ff4c52759e2c4ac70b7d517bc7fcdc1cda631ca0045271ddd1b192544f8a3e9"] + - id: attestation.id + type: string + stability: experimental + brief: > + The id of the build [software attestation](https://slsa.dev/attestation-model). + examples: ["123"] + - id: attestation.filename + type: string + stability: experimental + brief: > + The provenance filename of the built attestation which directly + relates to the build artifact filename. This filename SHOULD + accompany the artifact at publish time. See the + [SLSA Relationship](https://slsa.dev/spec/v1.0/distributing-provenance#relationship-between-artifacts-and-attestations) + specification for more information. + examples: + [ + "golang-binary-amd64-v0.1.0.attestation", + "docker-image-amd64-v0.1.0.intoto.json1", + "release-1.tar.gz.attestation", + "file-name-package.tar.gz.intoto.json1", + ] + - id: attestation.hash + type: string + stability: experimental + brief: > + The full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + of the built attestation. Some envelopes in the software attestation + space also refer to this as the [digest](https://github.com/in-toto/attestation/blob/main/spec/README.md#in-toto-attestation-framework-spec). + examples: + ["1b31dfcd5b7f9267bf2ff47651df1cfb9147b9e4df1f335accf65b4cda498408"] diff --git a/model/registry/cicd.yaml b/model/registry/cicd.yaml new file mode 100644 index 0000000000..16b381274b --- /dev/null +++ b/model/registry/cicd.yaml @@ -0,0 +1,77 @@ +groups: + - id: registry.cicd.pipeline + prefix: cicd.pipeline + type: attribute_group + brief: > + This group describes attributes specific to pipelines within a Continuous + Integration and Continuous Deployment (CI/CD) system. A + [pipeline](https://en.wikipedia.org/wiki/Pipeline_(computing)) in this + case is a series of steps that are performed in order to deliver a new + version of software. This aligns with the + [Britannica](https://www.britannica.com/dictionary/pipeline) definition + of a pipeline where a **pipeline** is the system for developing and + producing something. In the context of CI/CD, a pipeline produces or + delivers software. + attributes: + - id: name + type: string + stability: experimental + brief: > + The human readable name of the pipeline within a CI/CD system. + examples: + [ + "Build and Test", + "Lint", + "Deploy Go Project", + "deploy_to_environment", + ] + - id: run.id + type: string + stability: experimental + brief: > + The unique identifier of a pipeline run within a CI/CD system. + examples: ["120912"] + - id: task.name + type: string + stability: experimental + brief: > + The human readable name of a task within a pipeline. Task here most + closely aligns with a [computing process](https://en.wikipedia.org/wiki/Pipeline_(computing)) + in a pipeline. Other terms for tasks include commands, steps, and + procedures. + examples: ["Run GoLang Linter", "Go Build", "go-test", "deploy_binary"] + - id: task.run.id + type: string + stability: experimental + brief: > + The unique identifier of a task run within a pipeline. + examples: ["12097"] + - id: task.run.url.full + type: string + stability: experimental + brief: > + The [URL](https://en.wikipedia.org/wiki/URL) of the pipeline run + providing the complete address in order to locate and identify the pipeline run. + examples: + [ + "https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075", + ] + - id: task.type + type: + members: + - id: build + value: build + brief: build + stability: experimental + - id: test + value: test + brief: test + stability: experimental + - id: deploy + value: deploy + brief: deploy + stability: experimental + stability: experimental + brief: > + The type of the task within a pipeline. + examples: ["build", "test", "deploy"] diff --git a/model/registry/deployment.yaml b/model/registry/deployment.yaml index 0d4b6699bb..2cf5ec0666 100644 --- a/model/registry/deployment.yaml +++ b/model/registry/deployment.yaml @@ -6,18 +6,44 @@ groups: brief: > This document defines attributes for software deployments. attributes: - - id: environment + - id: name + type: string + stability: experimental + brief: > + The name of the deployment. + examples: ['deploy my app', 'deploy-frontend'] + - id: id + type: string + stability: experimental + brief: > + The id of the deployment. + examples: ['1208'] + - id: status + type: + members: + - id: failed + value: failed + brief: failed + stability: experimental + - id: succeeded + value: succeeded + brief: succeeded + stability: experimental + brief: > + The status of the deployment. + stability: experimental + - id: environment.name type: string stability: experimental brief: > Name of the [deployment environment](https://wikipedia.org/wiki/Deployment_environment) (aka deployment tier). note: | - `deployment.environment` does not affect the uniqueness constraints defined through + `deployment.environment.name` does not affect the uniqueness constraints defined through the `service.namespace`, `service.name` and `service.instance.id` resource attributes. This implies that resources carrying the following attribute combinations MUST be considered to be identifying the same service: - * `service.name=frontend`, `deployment.environment=production` - * `service.name=frontend`, `deployment.environment=staging`. + * `service.name=frontend`, `deployment.environment.name=production` + * `service.name=frontend`, `deployment.environment.name=staging`. examples: ['staging', 'production'] diff --git a/model/registry/deprecated/deployment.yaml b/model/registry/deprecated/deployment.yaml new file mode 100644 index 0000000000..fa02533e25 --- /dev/null +++ b/model/registry/deprecated/deployment.yaml @@ -0,0 +1,14 @@ +groups: + - id: registry.deployment.deprecated + prefix: deployment + type: attribute_group + brief: > + "Describes deprecated deployment attributes." + attributes: + - id: environment + type: string + stability: experimental + deprecated: 'Deprecated, use `deployment.environment.name` instead.' + brief: > + 'Deprecated, use `deployment.environment.name` instead.' + examples: ['staging', 'production'] diff --git a/model/registry/test.yaml b/model/registry/test.yaml new file mode 100644 index 0000000000..3f62dd02f5 --- /dev/null +++ b/model/registry/test.yaml @@ -0,0 +1,79 @@ +groups: + - id: registry.test + prefix: test + type: attribute_group + brief: > + This group describes attributes specific to + [software tests](https://en.wikipedia.org/wiki/Software_testing). + attributes: + - id: suite.name + type: string + stability: experimental + brief: > + The human readable name of a [test suite](https://en.wikipedia.org/wiki/Test_suite). + examples: ["TestSuite1"] + - id: suite.run.status + type: + members: + - id: success + value: success + brief: success + stability: experimental + - id: failure + value: failure + brief: failure + stability: experimental + - id: skipped + value: skipped + brief: skipped + stability: experimental + - id: aborted + value: aborted + brief: aborted + stability: experimental + - id: timed_out + value: timed_out + brief: timed_out + stability: experimental + - id: in_progress + value: in_progress + brief: in_progress + stability: experimental + stability: experimental + brief: > + The status of the test suite run. + examples: + [ + "success", + "failure", + "skipped", + "aborted", + "timed_out", + "in_progress", + ] + - id: case.name + type: string + stability: experimental + brief: > + The fully qualified human readable name of the [test case](https://en.wikipedia.org/wiki/Test_case). + examples: + [ + "org.example.TestCase1.test1", + "example/tests/TestCase1.test1", + "ExampleTestCase1_test1", + ] + - id: case.result.status + type: + members: + - id: pass + value: pass + brief: pass + stability: experimental + - id: fail + value: fail + brief: fail + stability: experimental + stability: experimental + brief: > + The status of the actual test case result from test execution. + examples: ["pass", "fail"] diff --git a/model/registry/vcs.yaml b/model/registry/vcs.yaml new file mode 100644 index 0000000000..a04ca9122e --- /dev/null +++ b/model/registry/vcs.yaml @@ -0,0 +1,86 @@ +groups: + - id: registry.vcs.repository + prefix: vcs.repository + type: attribute_group + brief: > + This group defines the attributes for + [Version Control Systems (VCS)](https://en.wikipedia.org/wiki/Version_control). + attributes: + - id: url.full + type: string + stability: experimental + brief: > + The [URL](https://en.wikipedia.org/wiki/URL) of the repository + providing the complete address in order to locate and identify the + repository. + examples: + [ + "https://github.com/opentelemetry/open-telemetry-collector-contrib", + "https://gitlab.com/my-org/my-project/my-projects-project/repo", + ] + - id: ref.name + type: string + stability: experimental + brief: > + The name of the + [reference](https://git-scm.com/docs/gitglossary#def_ref) such as + **branch** or **tag** in the repository. + examples: ["my-feature-branch", "tag-1-test"] + - id: ref.type + type: + members: + - id: branch + value: branch + brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" + stability: experimental + - id: tag + value: tag + brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" + stability: experimental + stability: experimental + brief: > + The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. + examples: ["branch", "tag"] + - id: ref.revision + type: string + stability: experimental + brief: > + The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), + The revision most often refers to a commit object in Git, or a revision number in SVN. + note: | + The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + of the recorded change to a ref within a repository pointing to a + commit [commit](https://git-scm.com/docs/git-commit) object. It does + not necessarily have to be a hash; it can simply define a + [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) + which is an integer that is monotonically increasing. In cases where + it is identical to the `ref.name`, it SHOULD still be included. It is + up to the implementer to decide which value to set as the revision + based on the VCS system and situational context. + examples: + [ + "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", + "main", + "123", + "HEAD", + ] + - id: change.title + type: string + stability: experimental + brief: > + The human readable title of the change (pull request/merge request). + This title is often a brief summary of the change and may get merged + in to a ref as the commit summary. + examples: + [ + "Fixes broken thing", + "feat: add my new feature", + "[chore] update dependency", + ] + - id: change.id + type: string + stability: experimental + brief: > + The ID of the change (pull request/merge request) if applicable. This + is usually a unique (within repository) identifier generated by the VCS system. + examples: ["123"] diff --git a/model/resource/deployment_environment.yaml b/model/resource/deployment_environment.yaml index c9a54bc7fa..cd3f2ee518 100644 --- a/model/resource/deployment_environment.yaml +++ b/model/resource/deployment_environment.yaml @@ -4,5 +4,5 @@ groups: brief: > The software deployment. attributes: - - ref: deployment.environment + - ref: deployment.environment.name requirement_level: recommended diff --git a/schema-next.yaml b/schema-next.yaml index 3539f102a7..39802f8de6 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -4,6 +4,10 @@ versions: next: all: changes: + # https://github.com/open-telemetry/semantic-conventions/pull/1075 + - rename_attributes: + attribute_map: + deployment.environment: deployment.environment.name # https://github.com/open-telemetry/semantic-conventions/pull/1245 - rename_attributes: attribute_map: diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index f698ae6754..f0d8849c7f 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -9,6 +9,7 @@ acronyms: - AI - iOS - AWS + - CICD - CloudEvents - CPU - CosmosDB @@ -32,3 +33,4 @@ acronyms: - SignalR - TLS - URL + - VCS