[vcs] add vcs.change.time_to_merge metric (open-telemetry#1685)

Co-authored-by: Liudmila Molkova <[email protected]>
Co-authored-by: Joao Grassi <[email protected]>

Author: 3 people

.chloggen/vcs-ttm.yaml

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

docs/attributes-registry/vcs.md

@@ -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-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-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-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-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-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-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-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-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. [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. [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. [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. [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. [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-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-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-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. [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) |
 
-**[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
 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)
+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.
+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.
 
-**[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),
+**[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
 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)
+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.
+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.
 
-**[3] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same
+**[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.
 
-**[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.
 
 ---