Semantic conventions for CICD metrics

Status: Development

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.

Guidance on per pipeline run metrics

It might be useful to gather metrics specific to each pipeline run.
Examples of such metrics include:

• host metrics like cpu, memory, disk of the worker on which a pipeline run executes
• container metrics like cpu, memory requests and limits
• runtime metrics of any processes executed as part of the pipeline run like JVM metrics

These metrics could be used to correlate build failures with environment issues like overload or out-of-memory. They could also be used in pipeline-level aggregations to inform adjustements of allocated worker resources.

When reporting host, container, runtime, and other metrics in CI/CD pipelines, instrumentation authors and application developers SHOULD use applicable CICD and VCS resource conventions and MAY also associate all or specific metrics with cicd.pipeline.run to correlate them with run information.

The cicd.pipeline.run entity identifies a pipeline run. Associating it with metrics inherently causes high cardinality and may increase costs with some metric storage backends. Thus, cicd.pipeline.run entity MUST be opt-in.

Metric: cicd.pipeline.run.duration

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
cicd.pipeline.run.duration	Histogram	s	Duration of a pipeline run grouped by pipeline, state and result.		cicd.pipeline

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cicd.pipeline.name		Required	string	The human readable name of the pipeline within a CI/CD system.	Build and Test; Lint; Deploy Go Project; deploy_to_environment
cicd.pipeline.run.state		Required	string	The pipeline run goes through these states during its lifecycle.	pending; executing; finalizing
cicd.pipeline.result		Conditionally Required [1]	string	The result of a pipeline run.	success; failure; timeout; skipped
error.type		Conditionally Required If and only if the pipeline run failed.	string	Describes a class of error the operation ended with. [2]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500

[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.
error	The pipeline run failed due to an error in the CICD system, eg. due to the worker being killed.
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.
skip	The pipeline run was skipped, eg. due to a precondition not being met.
success	The pipeline run finished successfully.
timeout	A timeout caused the pipeline run to be interrupted.

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).
finalizing	The finalizing state spans from when the run has finished executing (eg. cleanup of run resources).
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).

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.

Metric: cicd.pipeline.run.active

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
cicd.pipeline.run.active	UpDownCounter	{run}	The number of pipeline runs currently active in the system by state.		cicd.pipeline

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cicd.pipeline.name		Required	string	The human readable name of the pipeline within a CI/CD system.	Build and Test; Lint; Deploy Go Project; deploy_to_environment
cicd.pipeline.run.state		Required	string	The pipeline run goes through these states during its lifecycle.	pending; executing; finalizing

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).
finalizing	The finalizing state spans from when the run has finished executing (eg. cleanup of run resources).
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).

Metric: cicd.worker.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
cicd.worker.count	UpDownCounter	{count}	The number of workers on the CICD system by state.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cicd.worker.state		Required	string	The state of a CICD worker / agent.	idle; busy; down

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]
busy	The worker is performing work for the CICD system.
offline	The worker is not available to the CICD system (disconnected / down).

[1]: Pipelines might have conditions on which workers they are able to run so not every worker might be available to every pipeline.

Metric: cicd.pipeline.run.errors

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
cicd.pipeline.run.errors	Counter	{error}	The number of errors encountered in pipeline runs (eg. compile, test failures). [1]		cicd.pipeline

[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.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cicd.pipeline.name		Required	string	The human readable name of the pipeline within a CI/CD system.	Build and Test; Lint; Deploy Go Project; deploy_to_environment
error.type		Required	string	Describes a class of error the operation ended with. [1]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500

[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.

Metric: cicd.system.errors

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
cicd.system.errors	Counter	{error}	The number of errors in a component of the CICD system (eg. controller, scheduler, agent). [1]

[1]: Errors in pipeline run execution are explicitly excluded. Ie a test failure is not counted in this metric.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
cicd.system.component		Required	string	The name of a component of the CICD system.	controller; scheduler; agent
error.type		Required	string	Describes a class of error the operation ended with. [1]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500

[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.

VCS Metrics

The conventions described in this section are specific to Version Control Systems.

Disclaimer: These are initial VCS metrics and attributes but more may be added in the future.

Metric: vcs.change.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.change.count	UpDownCounter	{change}	The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged).		vcs.repo

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.change.state		Required	string	The state of the change (pull request/merge request/changelist).	open; closed; merged
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

[1] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[2] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

vcs.change.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
closed	Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request.
merged	Merged indicates that the change has been successfully integrated into the target codebase.
open	Open means the change is currently active and under review. It hasn’t been merged into the target branch yet, and it’s still possible to make changes or add comments.
wip	WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes.

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

Metric: vcs.change.duration

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.change.duration	Gauge	s	The time duration a change (pull request/merge request/changelist) has been in a given state.		vcs.repo

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.change.state		Required	string	The state of the change (pull request/merge request/changelist).	open; closed; merged
vcs.ref.head.name		Required	string	The name of the reference such as branch or tag in the repository. [1]	my-feature-branch; tag-1-test
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [2]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [3]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

[1] vcs.ref.head.name: head refers to where you are right now; the current reference at a given time.

[2] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[3] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

vcs.change.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
closed	Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, the issue being resolved in another way, or the author deciding to withdraw the request.
merged	Merged indicates that the change has been successfully integrated into the target codebase.
open	Open means the change is currently active and under review. It hasn’t been merged into the target branch yet, and it’s still possible to make changes or add comments.
wip	WIP (work-in-progress, draft) means the change is still in progress and not yet ready for a full review. It might still undergo significant changes.

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

Metric: vcs.change.time_to_approval

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.change.time_to_approval	Gauge	s	The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval.		vcs.repo; vcs.ref

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.ref.head.name		Required	string	The name of the reference such as branch or tag in the repository. [1]	my-feature-branch; tag-1-test
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [2]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.ref.base.name		Recommended	string	The name of the reference such as branch or tag in the repository. [3]	my-feature-branch; tag-1-test
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [4]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket
vcs.ref.base.revision		Opt-In	string	The revision, literally revised version, The revision most often refers to a commit object in Git, or a revision number in SVN. [5]	9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc; main; 123; HEAD
vcs.ref.head.revision		Opt-In	string	The revision, literally revised version, The revision most often refers to a commit object in Git, or a revision number in SVN. [6]	9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc; main; 123; HEAD

[1] vcs.ref.head.name: head refers to where you are right now; the current reference at a given time.

[2] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[3] vcs.ref.base.name: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits.

[4] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

[5] vcs.ref.base.revision: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits. The revision can be a full hash value (see glossary), of the recorded change to a ref within a repository pointing to a commit commit object. It does not necessarily have to be a hash; it can simply define a revision number which is an integer that is monotonically increasing. In cases where it is identical to the ref.base.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.

[6] vcs.ref.head.revision: head refers to where you are right now; the current reference at a given time.The revision can be a full hash value (see glossary), of the recorded change to a ref within a repository pointing to a commit commit object. It does not necessarily have to be a hash; it can simply define a revision number which is an integer that is monotonically increasing. In cases where it is identical to the ref.head.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.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

Metric: vcs.change.time_to_merge

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.change.time_to_merge	Gauge	s	The amount of time since its creation it took a change (pull request/merge request/changelist) to get merged into the target(base) ref.		vcs.repo; vcs.ref

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.ref.head.name		Required	string	The name of the reference such as branch or tag in the repository. [1]	my-feature-branch; tag-1-test
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [2]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.ref.base.name		Recommended	string	The name of the reference such as branch or tag in the repository. [3]	my-feature-branch; tag-1-test
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [4]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket
vcs.ref.base.revision		Opt-In	string	The revision, literally revised version, The revision most often refers to a commit object in Git, or a revision number in SVN. [5]	9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc; main; 123; HEAD
vcs.ref.head.revision		Opt-In	string	The revision, literally revised version, The revision most often refers to a commit object in Git, or a revision number in SVN. [6]	9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc; main; 123; HEAD

[1] vcs.ref.head.name: head refers to where you are right now; the current reference at a given time.

[2] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[3] vcs.ref.base.name: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits.

[4] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

[5] vcs.ref.base.revision: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits. The revision can be a full hash value (see glossary), of the recorded change to a ref within a repository pointing to a commit commit object. It does not necessarily have to be a hash; it can simply define a revision number which is an integer that is monotonically increasing. In cases where it is identical to the ref.base.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.

[6] vcs.ref.head.revision: head refers to where you are right now; the current reference at a given time.The revision can be a full hash value (see glossary), of the recorded change to a ref within a repository pointing to a commit commit object. It does not necessarily have to be a hash; it can simply define a revision number which is an integer that is monotonically increasing. In cases where it is identical to the ref.head.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.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

Metric: vcs.repository.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.repository.count	UpDownCounter	{repository}	The number of repositories in an organization.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

Metric: vcs.ref.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.ref.count	UpDownCounter	{ref}	The number of refs of type branch or tag in a repository.		vcs.repo

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.ref.type		Required	string	The type of the reference in the repository.	branch; tag
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

[1] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[2] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

vcs.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
tag	tag

Metric: vcs.ref.lines_delta

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.ref.lines_delta	Gauge	{line}	The number of lines added/removed in a ref (branch) relative to the ref from the vcs.ref.base.name attribute. [1]		vcs.repo

[1]: This metric should be reported for each vcs.line_change.type value. For example if a ref added 3 lines and removed 2 lines, instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). If number of lines added/removed should be calculated from the start of time, then vcs.ref.base.name SHOULD be set to an empty string.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.line_change.type		Required	string	The type of line change being measured on a branch or change.	added; removed
vcs.ref.base.name		Required	string	The name of the reference such as branch or tag in the repository. [1]	my-feature-branch; tag-1-test
vcs.ref.base.type		Required	string	The type of the reference in the repository. [2]	branch; tag
vcs.ref.head.name		Required	string	The name of the reference such as branch or tag in the repository. [3]	my-feature-branch; tag-1-test
vcs.ref.head.type		Required	string	The type of the reference in the repository. [4]	branch; tag
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [5]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.change.id		Conditionally Required if a change is associate with the ref.	string	The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system.	123
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [6]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

[1] vcs.ref.base.name: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits.

[2] vcs.ref.base.type: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits.

[3] vcs.ref.head.name: head refers to where you are right now; the current reference at a given time.

[4] vcs.ref.head.type: head refers to where you are right now; the current reference at a given time.

[5] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[6] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

vcs.line_change.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
added	How many lines were added.
removed	How many lines were removed.

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

vcs.ref.base.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
tag	tag

vcs.ref.head.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
tag	tag

Metric: vcs.ref.revisions_delta

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.ref.revisions_delta	Gauge	{revision}	The number of revisions (commits) a ref (branch) is ahead/behind the branch from the vcs.ref.base.name attribute. [1]		vcs.repo

[1]: This metric should be reported for each vcs.revision_delta.direction value. For example if branch a is 3 commits behind and 2 commits ahead of trunk, instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and vcs.ref.base.name is set to trunk.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.ref.base.name		Required	string	The name of the reference such as branch or tag in the repository. [1]	my-feature-branch; tag-1-test
vcs.ref.base.type		Required	string	The type of the reference in the repository. [2]	branch; tag
vcs.ref.head.name		Required	string	The name of the reference such as branch or tag in the repository. [3]	my-feature-branch; tag-1-test
vcs.ref.head.type		Required	string	The type of the reference in the repository. [4]	branch; tag
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [5]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.revision_delta.direction		Required	string	The type of revision comparison.	ahead; behind
vcs.change.id		Conditionally Required if a change is associate with the ref.	string	The ID of the change (pull request/merge request/changelist) if applicable. This is usually a unique (within repository) identifier generated by the VCS system.	123
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [6]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

[1] vcs.ref.base.name: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits.

[2] vcs.ref.base.type: base refers to the starting point of a change. For example, main would be the base reference of type branch if you’ve created a new reference of type branch from it and created new commits.

[3] vcs.ref.head.name: head refers to where you are right now; the current reference at a given time.

[4] vcs.ref.head.type: head refers to where you are right now; the current reference at a given time.

[5] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[6] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

vcs.ref.base.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
tag	tag

vcs.ref.head.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
tag	tag

vcs.revision_delta.direction 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
ahead	How many revisions the change is ahead of the target ref.
behind	How many revisions the change is behind the target ref.

Metric: vcs.ref.time

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.ref.time	Gauge	s	Time a ref (branch) created from the default branch (trunk) has existed. The ref.type attribute will always be branch.		vcs.repo

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.ref.head.name		Required	string	The name of the reference such as branch or tag in the repository. [1]	my-feature-branch; tag-1-test
vcs.ref.head.type		Required	string	The type of the reference in the repository. [2]	branch; tag
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [3]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [4]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

[1] vcs.ref.head.name: head refers to where you are right now; the current reference at a given time.

[2] vcs.ref.head.type: head refers to where you are right now; the current reference at a given time.

[3] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[4] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab

vcs.ref.head.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
tag	tag

Metric: vcs.contributor.count

This metric is opt-in.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
vcs.contributor.count	Gauge	{contributor}	The number of unique contributors to a repository.		vcs.repo

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
vcs.repository.url.full		Required	string	The canonical URL of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [1]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.owner.name		Recommended	string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.repository.name		Recommended	string	The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [2]	semantic-conventions; my-cool-repo
vcs.provider.name		Opt-In	string	The name of the version control system provider.	github; gitlab; gitea; bitbucket

[1] vcs.repository.url.full: In Git Version Control Systems, the canonical URL SHOULD NOT include the .git extension.

[2] vcs.repository.name: Due to it only being the name, it can clash with forks of the same repository if collecting telemetry across multiple orgs or groups in the same backends.

vcs.provider.name 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
bitbucket	Bitbucket
gitea	Gitea
github	GitHub
gitlab	GitLab