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

[vcs] add `vcs.change.time_to_merge` metric (#1685) 

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
This commit is contained in:
Adriel Perkins 2025-01-23 15:05:46 -05:00 committed by GitHub
parent 43654752b1
commit 7bde041ce5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 342 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
.chloggen/vcs-ttm.yaml Executable file
View File

@ -0,0 +1,22 @@
# 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: enhancement
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: vcs
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Add `vcs.change.time_to_merge` metric.
# 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: [1685]
# (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:

64
docs/attributes-registry/vcs.md
View File

@ -19,42 +19,62 @@ This group defines the attributes for [Version Control Systems (VCS)](https://wi
| <a id="vcs-change-state" href="#vcs-change-state">`vcs.change.state`</a> | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | <a id="vcs-change-state" href="#vcs-change-state">`vcs.change.state`</a> | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-change-title" href="#vcs-change-title">`vcs.change.title`</a> | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | <a id="vcs-change-title" href="#vcs-change-title">`vcs.change.title`</a> | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-line-change-type" href="#vcs-line-change-type">`vcs.line_change.type`</a> | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | <a id="vcs-line-change-type" href="#vcs-line-change-type">`vcs.line_change.type`</a> | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-ref-base-name" href="#vcs-ref-base-name">`vcs.ref.base.name`</a> | 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) | | <a id="vcs-ref-base-name" href="#vcs-ref-base-name">`vcs.ref.base.name`</a> | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-ref-base-revision" href="#vcs-ref-base-revision">`vcs.ref.base.revision`</a> | 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) | | <a id="vcs-ref-base-revision" href="#vcs-ref-base-revision">`vcs.ref.base.revision`</a> | 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. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-ref-base-type" href="#vcs-ref-base-type">`vcs.ref.base.type`</a> | 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) | | <a id="vcs-ref-base-type" href="#vcs-ref-base-type">`vcs.ref.base.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [3] | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-ref-head-name" href="#vcs-ref-head-name">`vcs.ref.head.name`</a> | 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) | | <a id="vcs-ref-head-name" href="#vcs-ref-head-name">`vcs.ref.head.name`</a> | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [4] | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-ref-head-revision" href="#vcs-ref-head-revision">`vcs.ref.head.revision`</a> | 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. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | <a id="vcs-ref-head-revision" href="#vcs-ref-head-revision">`vcs.ref.head.revision`</a> | 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. [5] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-ref-head-type" href="#vcs-ref-head-type">`vcs.ref.head.type`</a> | 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) | | <a id="vcs-ref-head-type" href="#vcs-ref-head-type">`vcs.ref.head.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [6] | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-ref-type" href="#vcs-ref-type">`vcs.ref.type`</a> | 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) | | <a id="vcs-ref-type" href="#vcs-ref-type">`vcs.ref.type`</a> | 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) |
| <a id="vcs-repository-name" href="#vcs-repository-name">`vcs.repository.name`</a> | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | <a id="vcs-repository-name" href="#vcs-repository-name">`vcs.repository.name`</a> | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-repository-url-full" href="#vcs-repository-url-full">`vcs.repository.url.full`</a> | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [4] | `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) | | <a id="vcs-repository-url-full" href="#vcs-repository-url-full">`vcs.repository.url.full`</a> | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| <a id="vcs-revision-delta-direction" href="#vcs-revision-delta-direction">`vcs.revision_delta.direction`</a> | string | The type of revision comparison. | `ahead`; `behind` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | <a id="vcs-revision-delta-direction" href="#vcs-revision-delta-direction">`vcs.revision_delta.direction`</a> | string | The type of revision comparison. | `ahead`; `behind` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1] `vcs.ref.base.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), **[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)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a 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 commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a not necessarily have to be a hash; it can simply define a [revision
[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) 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 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 it is identical to the `ref.base.name`, it SHOULD still be included.
up to the implementer to decide which value to set as the revision It is up to the implementer to decide which value to set as the
based on the VCS system and situational context. revision based on the VCS system and situational context.
**[2] `vcs.ref.head.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), **[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)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a 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 commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a not necessarily have to be a hash; it can simply define a [revision
[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) 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 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 it is identical to the `ref.head.name`, it SHOULD still be included.
up to the implementer to decide which value to set as the revision It is up to the implementer to decide which value to set as the
based on the VCS system and situational context. revision based on the VCS system and situational context.
**[3] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same **[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 repository if collecting telemetry across multiple orgs or groups in
the same backends. the same backends.
**[4] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include **[8] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
the `.git` extension. the `.git` extension.
--- ---

215
docs/cicd/cicd-metrics.md
View File

@ -20,6 +20,7 @@ linkTitle: CICD metrics
- [Metric: `vcs.change.count`](#metric-vcschangecount) - [Metric: `vcs.change.count`](#metric-vcschangecount)
- [Metric: `vcs.change.duration`](#metric-vcschangeduration) - [Metric: `vcs.change.duration`](#metric-vcschangeduration)
- [Metric: `vcs.change.time_to_approval`](#metric-vcschangetime_to_approval) - [Metric: `vcs.change.time_to_approval`](#metric-vcschangetime_to_approval)
- [Metric: `vcs.change.time_to_merge`](#metric-vcschangetime_to_merge)
- [Metric: `vcs.repository.count`](#metric-vcsrepositorycount) - [Metric: `vcs.repository.count`](#metric-vcsrepositorycount)
- [Metric: `vcs.ref.count`](#metric-vcsrefcount) - [Metric: `vcs.ref.count`](#metric-vcsrefcount)
- [Metric: `vcs.ref.lines_delta`](#metric-vcsreflines_delta) - [Metric: `vcs.ref.lines_delta`](#metric-vcsreflines_delta)
@ -367,14 +368,17 @@ This metric is [recommended][MetricRecommended].
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---| |---|---|---|---|---|---|
| [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include **[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. the `.git` extension.
**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same **[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 repository if collecting telemetry across multiple orgs or groups in
the same backends. the same backends.
@ -407,21 +411,126 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | | 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](https://img.shields.io/badge/-experimental-blue) | | `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](https://img.shields.io/badge/-experimental-blue) |
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---| |---|---|---|---|---|---|
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.base.revision`](/docs/attributes-registry/vcs.md) | 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. [5] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.revision`](/docs/attributes-registry/vcs.md) | 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. [6] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include **[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. the `.git` extension.
**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same **[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 repository if collecting telemetry across multiple orgs or groups in
the same backends. 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)](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.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)](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.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.
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### Metric: `vcs.change.time_to_merge`
This metric is [recommended][MetricRecommended].
<!-- semconv metric.vcs.change.time_to_merge -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- |
| `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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.base.revision`](/docs/attributes-registry/vcs.md) | 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. [5] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.revision`](/docs/attributes-registry/vcs.md) | 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. [6] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[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)](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.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)](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.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.
<!-- markdownlint-restore --> <!-- markdownlint-restore -->
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT --> <!-- END AUTOGENERATED TEXT -->
@ -440,7 +549,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | | Name | Instrument Type | Unit (UCUM) | Description | Stability |
| -------- | --------------- | ----------- | -------------- | --------- | | -------- | --------------- | ----------- | -------------- | --------- |
| `vcs.repository.count` | UpDownCounter | `{repository}` | The number of repositories in an organization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vcs.repository.count` | UpDownCounter | `{repository}` | The number of repositories in an organization. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
<!-- markdownlint-restore --> <!-- markdownlint-restore -->
<!-- prettier-ignore-end --> <!-- prettier-ignore-end -->
@ -460,7 +569,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | | 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](https://img.shields.io/badge/-experimental-blue) | | `vcs.ref.count` | UpDownCounter | `{ref}` | The number of refs of type branch or tag in a repository. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---| |---|---|---|---|---|---|
@ -502,7 +611,7 @@ This metric is [recommended][MetricRecommended].
| Name | Instrument Type | Unit (UCUM) | Description | Stability | | 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](https://img.shields.io/badge/-experimental-blue) | | `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](https://img.shields.io/badge/-experimental-blue) |
**[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, **[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). instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers).
@ -511,18 +620,32 @@ If number of lines added/removed should be calculated from the start of time, th
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---| |---|---|---|---|---|---|
| [`vcs.line_change.type`](/docs/attributes-registry/vcs.md) | string | The type of line change being measured on a branch or change. | `added`; `removed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.line_change.type`](/docs/attributes-registry/vcs.md) | string | The type of line change being measured on a branch or change. | `added`; `removed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [2] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [4] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.change.id`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include **[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. the `.git` extension.
**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same **[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 repository if collecting telemetry across multiple orgs or groups in
the same backends. the same backends.
@ -578,19 +701,33 @@ instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers)
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---| |---|---|---|---|---|---|
| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [2] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [3] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [4] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.revision_delta.direction`](/docs/attributes-registry/vcs.md) | string | The type of revision comparison. | `ahead`; `behind` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.revision_delta.direction`](/docs/attributes-registry/vcs.md) | string | The type of revision comparison. | `ahead`; `behind` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.change.id`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include **[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. the `.git` extension.
**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same **[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 repository if collecting telemetry across multiple orgs or groups in
the same backends. the same backends.
@ -643,15 +780,21 @@ This metric is [recommended][MetricRecommended].
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---| |---|---|---|---|---|---|
| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [1] | `my-feature-branch`; `tag-1-test` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. [2] | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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](https://img.shields.io/badge/-experimental-blue) | | [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | 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` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
**[1] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include **[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. the `.git` extension.
**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same **[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 repository if collecting telemetry across multiple orgs or groups in
the same backends. the same backends.

52
model/vcs/metrics.yaml
View File

@ -5,7 +5,7 @@ groups:
brief: 'The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged)' brief: 'The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. open or merged)'
instrument: updowncounter instrument: updowncounter
unit: "{change}" unit: "{change}"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.change.state - ref: vcs.change.state
requirement_level: required requirement_level: required
@ -19,7 +19,7 @@ groups:
brief: 'The time duration a change (pull request/merge request/changelist) has been in a given state.' brief: 'The time duration a change (pull request/merge request/changelist) has been in a given state.'
instrument: gauge instrument: gauge
unit: "s" unit: "s"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.repository.url.full - ref: vcs.repository.url.full
requirement_level: required requirement_level: required
@ -32,10 +32,10 @@ groups:
- id: metric.vcs.change.time_to_approval - id: metric.vcs.change.time_to_approval
type: metric type: metric
metric_name: vcs.change.time_to_approval metric_name: vcs.change.time_to_approval
brief: 'The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval' brief: 'The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval.'
instrument: gauge instrument: gauge
unit: "s" unit: "s"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.repository.url.full - ref: vcs.repository.url.full
requirement_level: required requirement_level: required
@ -43,21 +43,47 @@ groups:
requirement_level: recommended requirement_level: recommended
- ref: vcs.ref.head.name - ref: vcs.ref.head.name
requirement_level: required requirement_level: required
- ref: vcs.ref.head.revision
requirement_level: opt_in
- ref: vcs.ref.base.name
requirement_level: recommended
- ref: vcs.ref.base.revision
requirement_level: opt_in
- id: metric.vcs.change.time_to_merge
type: metric
metric_name: vcs.change.time_to_merge
brief: 'The amount of time since its creation it took a change (pull request/merge request/changelist) to get merged into the target(base) ref.'
instrument: gauge
unit: "s"
stability: development
attributes:
- ref: vcs.repository.url.full
requirement_level: required
- ref: vcs.repository.name
requirement_level: recommended
- ref: vcs.ref.head.name
requirement_level: required
- ref: vcs.ref.head.revision
requirement_level: opt_in
- ref: vcs.ref.base.name
requirement_level: recommended
- ref: vcs.ref.base.revision
requirement_level: opt_in
- id: metric.vcs.repository.count - id: metric.vcs.repository.count
type: metric type: metric
metric_name: vcs.repository.count metric_name: vcs.repository.count
brief: 'The number of repositories in an organization' brief: 'The number of repositories in an organization.'
instrument: updowncounter instrument: updowncounter
unit: "{repository}" unit: "{repository}"
stability: experimental stability: development
attributes: [] attributes: []
- id: metric.vcs.ref.count - id: metric.vcs.ref.count
type: metric type: metric
metric_name: vcs.ref.count metric_name: vcs.ref.count
brief: 'The number of refs of type branch or tag in a repository' brief: 'The number of refs of type branch or tag in a repository.'
instrument: updowncounter instrument: updowncounter
unit: "{ref}" unit: "{ref}"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.repository.url.full - ref: vcs.repository.url.full
requirement_level: required requirement_level: required
@ -68,14 +94,14 @@ groups:
- id: metric.vcs.ref.lines_delta - id: metric.vcs.ref.lines_delta
type: metric type: metric
metric_name: vcs.ref.lines_delta metric_name: vcs.ref.lines_delta
brief: 'The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute' brief: 'The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute.'
note: | note: |
This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, 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). 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. 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.
instrument: gauge instrument: gauge
unit: "{line}" unit: "{line}"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.change.id - ref: vcs.change.id
requirement_level: requirement_level:
@ -103,7 +129,7 @@ groups:
instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`. instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`.
instrument: gauge instrument: gauge
unit: "{revision}" unit: "{revision}"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.change.id - ref: vcs.change.id
requirement_level: requirement_level:
@ -128,7 +154,7 @@ groups:
brief: 'Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch`' brief: 'Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch`'
instrument: gauge instrument: gauge
unit: "s" unit: "s"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.repository.url.full - ref: vcs.repository.url.full
requirement_level: required requirement_level: required
@ -144,7 +170,7 @@ groups:
brief: 'The number of unique contributors to a repository' brief: 'The number of unique contributors to a repository'
instrument: gauge instrument: gauge
unit: "{contributor}" unit: "{contributor}"
stability: experimental stability: development
attributes: attributes:
- ref: vcs.repository.url.full - ref: vcs.repository.url.full
requirement_level: required requirement_level: required

100
model/vcs/registry.yaml
View File

@ -8,7 +8,7 @@ groups:
attributes: attributes:
- id: vcs.repository.url.full - id: vcs.repository.url.full
type: string type: string
stability: experimental stability: development
brief: > brief: >
The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.)
of the repository providing the complete HTTP(S) address in order to of the repository providing the complete HTTP(S) address in order to
@ -23,7 +23,7 @@ groups:
] ]
- id: vcs.repository.name - id: vcs.repository.name
type: string type: string
stability: experimental stability: development
brief: > brief: >
The human readable name of the repository. It SHOULD NOT include any The human readable name of the repository. It SHOULD NOT include any
additional identifier like Group/SubGroup in GitLab or organization additional identifier like Group/SubGroup in GitLab or organization
@ -39,11 +39,15 @@ groups:
] ]
- id: vcs.ref.base.name - id: vcs.ref.base.name
type: string type: string
stability: experimental stability: development
brief: > brief: >
The name of the The name of the
[reference](https://git-scm.com/docs/gitglossary#def_ref) such as [reference](https://git-scm.com/docs/gitglossary#def_ref) such as
**branch** or **tag** in the repository. **branch** or **tag** in the repository.
note: |
`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.
examples: ["my-feature-branch", "tag-1-test"] examples: ["my-feature-branch", "tag-1-test"]
- id: vcs.ref.base.type - id: vcs.ref.base.type
type: type:
@ -51,31 +55,39 @@ groups:
- id: branch - id: branch
value: branch value: branch
brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
stability: experimental stability: development
- id: tag - id: tag
value: tag value: tag
brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
stability: experimental stability: development
stability: experimental stability: development
brief: > brief: >
The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository.
note: |
`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.
examples: ["branch", "tag"] examples: ["branch", "tag"]
- id: vcs.ref.base.revision - id: vcs.ref.base.revision
type: string type: string
stability: experimental stability: development
brief: > brief: >
The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), 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. The revision most often refers to a commit object in Git, or a revision number in SVN.
note: | note: |
The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), `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)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a 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 commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a not necessarily have to be a hash; it can simply define a [revision
[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) 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 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 it is identical to the `ref.base.name`, it SHOULD still be included.
up to the implementer to decide which value to set as the revision It is up to the implementer to decide which value to set as the
based on the VCS system and situational context. revision based on the VCS system and situational context.
examples: examples:
[ [
"9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc",
@ -85,11 +97,14 @@ groups:
] ]
- id: vcs.ref.head.name - id: vcs.ref.head.name
type: string type: string
stability: experimental stability: development
brief: > brief: >
The name of the The name of the
[reference](https://git-scm.com/docs/gitglossary#def_ref) such as [reference](https://git-scm.com/docs/gitglossary#def_ref) such as
**branch** or **tag** in the repository. **branch** or **tag** in the repository.
note: |
`head` refers to where you are right now; the current reference at a
given time.
examples: ["my-feature-branch", "tag-1-test"] examples: ["my-feature-branch", "tag-1-test"]
- id: vcs.ref.head.type - id: vcs.ref.head.type
type: type:
@ -97,31 +112,36 @@ groups:
- id: branch - id: branch
value: branch value: branch
brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
stability: experimental stability: development
- id: tag - id: tag
value: tag value: tag
brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
stability: experimental stability: development
stability: experimental stability: development
brief: > brief: >
The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository.
note: |
`head` refers to where you are right now; the current reference at a
given time.
examples: ["branch", "tag"] examples: ["branch", "tag"]
- id: vcs.ref.head.revision - id: vcs.ref.head.revision
type: string type: string
stability: experimental stability: development
brief: > brief: >
The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), 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. The revision most often refers to a commit object in Git, or a revision number in SVN.
note: | note: |
The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), `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)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
of the recorded change to a ref within a repository pointing to a 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 commit [commit](https://git-scm.com/docs/git-commit) object. It does
not necessarily have to be a hash; it can simply define a not necessarily have to be a hash; it can simply define a [revision
[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) 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 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 it is identical to the `ref.head.name`, it SHOULD still be included.
up to the implementer to decide which value to set as the revision It is up to the implementer to decide which value to set as the
based on the VCS system and situational context. revision based on the VCS system and situational context.
examples: examples:
[ [
"9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc",
@ -135,12 +155,12 @@ groups:
- id: branch - id: branch
value: branch value: branch
brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
stability: experimental stability: development
- id: tag - id: tag
value: tag value: tag
brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
stability: experimental stability: development
stability: experimental stability: development
brief: > brief: >
The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository.
examples: ["branch", "tag"] examples: ["branch", "tag"]
@ -150,12 +170,12 @@ groups:
- id: behind - id: behind
value: behind value: behind
brief: "How many revisions the change is behind the target ref." brief: "How many revisions the change is behind the target ref."
stability: experimental stability: development
- id: ahead - id: ahead
value: ahead value: ahead
brief: "How many revisions the change is ahead of the target ref." brief: "How many revisions the change is ahead of the target ref."
stability: experimental stability: development
stability: experimental stability: development
brief: > brief: >
The type of revision comparison. The type of revision comparison.
examples: ["ahead", "behind"] examples: ["ahead", "behind"]
@ -165,18 +185,18 @@ groups:
- id: added - id: added
value: added value: added
brief: "How many lines were added." brief: "How many lines were added."
stability: experimental stability: development
- id: removed - id: removed
value: removed value: removed
brief: "How many lines were removed." brief: "How many lines were removed."
stability: experimental stability: development
stability: experimental stability: development
brief: > brief: >
The type of line change being measured on a branch or change. The type of line change being measured on a branch or change.
examples: ["added", "removed"] examples: ["added", "removed"]
- id: vcs.change.title - id: vcs.change.title
type: string type: string
stability: experimental stability: development
brief: > brief: >
The human readable title of the change (pull request/merge request/changelist). 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 This title is often a brief summary of the change and may get merged
@ -189,7 +209,7 @@ groups:
] ]
- id: vcs.change.id - id: vcs.change.id
type: string type: string
stability: experimental stability: development
brief: > brief: >
The ID of the change (pull request/merge request/changelist) if applicable. This 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. is usually a unique (within repository) identifier generated by the VCS system.
@ -200,22 +220,22 @@ groups:
- id: open - id: open
value: open value: open
brief: "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." brief: "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."
stability: experimental stability: development
- id: wip - id: wip
value: wip value: wip
brief: "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." brief: "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."
stability: experimental stability: development
- id: closed - id: closed
value: closed value: closed
brief: >- brief: >-
Closed means the merge request has been closed without merging. This can happen for various reasons, such as the changes being deemed unnecessary, 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. the issue being resolved in another way, or the author deciding to withdraw the request.
stability: experimental stability: development
- id: merged - id: merged
value: merged value: merged
brief: "Merged indicates that the change has been successfully integrated into the target codebase." brief: "Merged indicates that the change has been successfully integrated into the target codebase."
stability: experimental stability: development
stability: experimental stability: development
brief: > brief: >
The state of the change (pull request/merge request/changelist). The state of the change (pull request/merge request/changelist).
examples: ["open", "closed", "merged"] examples: ["open", "closed", "merged"]