VCS

• VCS Repository Attributes
• VCS Deprecated Attributes

VCS Repository Attributes

This group defines the attributes for Version Control Systems (VCS).

Attributes:

Key	Stability	Value Type	Description	Example Values
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
vcs.change.state		string	The state of the change (pull request/merge request/changelist).	open; closed; merged
vcs.change.title		string	The human readable title of the change (pull request/merge request/changelist). 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
vcs.line_change.type		string	The type of line change being measured on a branch or change.	added; removed
vcs.owner.name		string	The group owner within the version control system.	my-org; myteam; business-unit
vcs.provider.name		string	The name of the version control system provider.	github; gitlab; gitea; bitbucket
vcs.ref.base.name		string	The name of the reference such as branch or tag in the repository. [1]	my-feature-branch; tag-1-test
vcs.ref.base.revision		string	The revision, literally revised version, The revision most often refers to a commit object in Git, or a revision number in SVN. [2]	9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc; main; 123; HEAD
vcs.ref.base.type		string	The type of the reference in the repository. [3]	branch; tag
vcs.ref.head.name		string	The name of the reference such as branch or tag in the repository. [4]	my-feature-branch; tag-1-test
vcs.ref.head.revision		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.type		string	The type of the reference in the repository. [6]	branch; tag
vcs.ref.type		string	The type of the reference in the repository.	branch; tag
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. [7]	semantic-conventions; my-cool-repo
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. [8]	https://github.com/opentelemetry/open-telemetry-collector-contrib; https://gitlab.com/my-org/my-project/my-projects-project/repo
vcs.revision_delta.direction		string	The type of revision comparison.	ahead; behind

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

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

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

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

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

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

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

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

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

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.

VCS Deprecated Attributes

Describes deprecated vcs attributes.

Attributes:

Key	Stability	Value Type	Description	Example Values
vcs.repository.change.id	Replaced by vcs.change.id.	string	Deprecated, use vcs.change.id instead.	123
vcs.repository.change.title	Replaced by vcs.change.title.	string	Deprecated, use vcs.change.title instead.	Fixes broken thing; feat: add my new feature; [chore] update dependency
vcs.repository.ref.name	Replaced by vcs.ref.head.name.	string	Deprecated, use vcs.ref.head.name instead.	my-feature-branch; tag-1-test
vcs.repository.ref.revision	Replaced by vcs.ref.head.revision.	string	Deprecated, use vcs.ref.head.revision instead.	9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc; main; 123; HEAD
vcs.repository.ref.type	Replaced by vcs.ref.head.type.	string	Deprecated, use vcs.ref.head.type instead.	branch; tag

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