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

[cicd] add initial cicd attributes to registry (#1075)

This commit is contained in:
Adriel Perkins 2024-07-19 08:29:37 -04:00 committed by GitHub
parent 8c21da38ca
commit 5b640caf47
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
23 changed files with 610 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
.chloggen/cicd-reg-attr.yaml Executable file
View File

@ -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`.

8
.github/CODEOWNERS vendored
View File

@ -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

4
.github/ISSUE_TEMPLATE/bug_report.yaml vendored
View File

@ -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
@ -67,12 +69,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

4
.github/ISSUE_TEMPLATE/change_proposal.yaml vendored
View File

@ -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
@ -60,12 +62,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

4
.github/ISSUE_TEMPLATE/new-conventions.yaml vendored
View File

@ -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
@ -69,12 +71,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

5
.gitignore vendored
View File

@ -34,4 +34,7 @@ package-lock.json
.vscode
# Visual Studio
.vs/
.vs/
# Python
venv

2
.markdown_link_check_config.json
View File

@ -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": [

4
docs/attributes-registry/README.md
View File

@ -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)
@ -81,12 +83,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

35
docs/attributes-registry/artifact.md Normal file
View File

@ -0,0 +1,35 @@
<!--- Hugo front matter used to generate the website version of this page:
--->
<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
# 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.

28
docs/attributes-registry/cicd.md Normal file
View File

@ -0,0 +1,28 @@
<!--- Hugo front matter used to generate the website version of this page:
--->
<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
# CICD
## CICD Pipeline Attributes
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.
| 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](<https://en.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://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) |

33
docs/attributes-registry/deployment.md
View File

@ -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)<br>Deprecated, use `deployment.environment.name` instead. |

36
docs/attributes-registry/test.md Normal file
View File

@ -0,0 +1,36 @@
<!--- Hugo front matter used to generate the website version of this page:
--->
<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
# 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) |

37
docs/attributes-registry/vcs.md Normal file
View File

@ -0,0 +1,37 @@
<!--- Hugo front matter used to generate the website version of this page:
--->
<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
# 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) |

8
docs/resource/deployment-environment.md
View File

@ -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`.

97
model/registry/artifact.yaml Normal file
View File

@ -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"]

77
model/registry/cicd.yaml Normal file
View File

@ -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"]

34
model/registry/deployment.yaml
View File

@ -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']

14
model/registry/deprecated/deployment.yaml Normal file
View File

@ -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']

79
model/registry/test.yaml Normal file
View File

@ -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"]

86
model/registry/vcs.yaml Normal file
View File

@ -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"]

2
model/resource/deployment_environment.yaml
View File

@ -4,5 +4,5 @@ groups:
brief: >
The software deployment.
attributes:
- ref: deployment.environment
- ref: deployment.environment.name
requirement_level: recommended

4
schema-next.yaml
View File

@ -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:

2
templates/registry/markdown/weaver.yaml
View File

@ -9,6 +9,7 @@ acronyms:
- AI
- iOS
- AWS
- CICD
- CloudEvents
- CPU
- CosmosDB
@ -32,3 +33,4 @@ acronyms:
- SignalR
- TLS
- URL
- VCS