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
semantic-conventions/docs/cicd/cicd-metrics.md

32 KiB
Raw Blame History

Semantic Conventions for CICD Metrics

Status: Experimental

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) Experimental
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 Experimental
vcs.repository.url.full 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 Required Experimental
vcs.repository.name 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 Recommended Experimental

[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. Experimental
merged Merged indicates that the change has been successfully integrated into the target codebase. Experimental
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. Experimental
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. Experimental

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. Experimental
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 Experimental
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 Experimental
vcs.repository.url.full 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 Required Experimental
vcs.repository.name 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 Recommended Experimental

[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. Experimental
merged Merged indicates that the change has been successfully integrated into the target codebase. Experimental
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. Experimental
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. Experimental

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 Experimental
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 Experimental
vcs.repository.url.full 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 Required Experimental
vcs.repository.name 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 Recommended Experimental

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

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 Experimental

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

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

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

[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 Experimental
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 Experimental
vcs.ref.base.type string The type of the reference in the repository. branch; tag Required Experimental
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 Experimental
vcs.ref.head.type string The type of the reference in the repository. branch; tag Required Experimental
vcs.repository.url.full 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 Required Experimental
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. Experimental
vcs.repository.name 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 Recommended Experimental

[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.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. Experimental
removed How many lines were removed. Experimental

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

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

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

[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 Experimental
vcs.ref.base.type string The type of the reference in the repository. branch; tag Required Experimental
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 Experimental
vcs.ref.head.type string The type of the reference in the repository. branch; tag Required Experimental
vcs.repository.url.full 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 Required Experimental
vcs.revision_delta.direction string The type of revision comparison. ahead; behind Required Experimental
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. Experimental
vcs.repository.name 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 Recommended Experimental

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

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

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. Experimental
behind How many revisions the change is behind the target ref. Experimental

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 Experimental
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 Experimental
vcs.ref.head.type string The type of the reference in the repository. branch; tag Required Experimental
vcs.repository.url.full 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 Required Experimental
vcs.repository.name 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 Recommended Experimental

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

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

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