semantic-conventions/docs/cicd/cicd-metrics.md

Semantic Conventions for CICD Metrics

Status: Experimental

• VCS Metrics
  • Metric: vcs.change.count
  • Metric: vcs.change.duration
  • Metric: vcs.change.time_to_approval
  • Metric: vcs.repository.count
  • Metric: vcs.ref.count
  • Metric: vcs.ref.lines_delta
  • Metric: vcs.ref.revisions_delta
  • Metric: vcs.ref.time
  • Metric: vcs.contributor.count

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

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.change.state	string	The state of the change (pull request/merge request/changelist).	open; closed; merged	Required
vcs.repository.url.full	string	The 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	Required

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.

Metric: vcs.change.duration

This metric is recommended.

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

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.change.state	string	The state of the change (pull request/merge request/changelist).	open; closed; merged	Required
vcs.ref.head.name	string	The name of the reference such as branch or tag in the repository.	my-feature-branch; tag-1-test	Required
vcs.repository.url.full	string	The 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	Required

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.

Metric: vcs.change.time_to_approval

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
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

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.ref.head.name	string	The name of the reference such as branch or tag in the repository.	my-feature-branch; tag-1-test	Required
vcs.repository.url.full	string	The 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	Required

Metric: vcs.repository.count

This metric is recommended.

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

Metric: vcs.ref.count

This metric is recommended.

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

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.ref.type	string	The type of the reference in the repository.	branch; tag	Required
vcs.repository.url.full	string	The 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	Required

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

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

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.line_change.type	string	The type of line change being measured on a branch or change.	added; removed	Required
vcs.ref.base.name	string	The name of the reference such as branch or tag in the repository.	my-feature-branch; tag-1-test	Required
vcs.ref.base.type	string	The type of the reference in the repository.	branch; tag	Required
vcs.ref.head.name	string	The name of the reference such as branch or tag in the repository.	my-feature-branch; tag-1-test	Required
vcs.ref.head.type	string	The type of the reference in the repository.	branch; tag	Required
vcs.repository.url.full	string	The 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	Required
vcs.change.id	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	Conditionally Required if a change is associate with the ref.

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

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

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.ref.base.name	string	The name of the reference such as branch or tag in the repository.	my-feature-branch; tag-1-test	Required
vcs.ref.base.type	string	The type of the reference in the repository.	branch; tag	Required
vcs.ref.head.name	string	The name of the reference such as branch or tag in the repository.	my-feature-branch; tag-1-test	Required
vcs.ref.head.type	string	The type of the reference in the repository.	branch; tag	Required
vcs.repository.url.full	string	The 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	Required
vcs.revision_delta.direction	string	The type of revision comparison.	ahead; behind	Required
vcs.change.id	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	Conditionally Required if a change is associate with the ref.

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

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.ref.head.name	string	The name of the reference such as branch or tag in the repository.	my-feature-branch; tag-1-test	Required
vcs.ref.head.type	string	The type of the reference in the repository.	branch; tag	Required
vcs.repository.url.full	string	The 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	Required

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
vcs.contributor.count	Gauge	{contributor}	The number of unique contributors to a repository

Attribute	Type	Description	Examples	Requirement Level	Stability
vcs.repository.url.full	string	The 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	Required