diff --git a/.chloggen/vcs-ttm.yaml b/.chloggen/vcs-ttm.yaml new file mode 100755 index 0000000000..25f2671a70 --- /dev/null +++ b/.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: diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md index b17426a93c..2e47a9f003 100644 --- a/docs/attributes-registry/vcs.md +++ b/docs/attributes-registry/vcs.md @@ -19,42 +19,62 @@ This group defines the attributes for [Version Control Systems (VCS)](https://wi | `vcs.change.state` | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `vcs.line_change.type` | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.ref.base.name` | 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) | -| `vcs.ref.base.revision` | 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) | -| `vcs.ref.base.type` | 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) | -| `vcs.ref.head.name` | 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) | -| `vcs.ref.head.revision` | 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) | -| `vcs.ref.head.type` | 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) | +| `vcs.ref.base.name` | 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) | +| `vcs.ref.base.revision` | 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) | +| `vcs.ref.base.type` | 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) | +| `vcs.ref.head.name` | 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) | +| `vcs.ref.head.revision` | 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) | +| `vcs.ref.head.type` | 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) | | `vcs.ref.type` | 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) | -| `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. [3] | `semantic-conventions`; `my-cool-repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `vcs.repository.url.full` | 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) | +| `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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.repository.url.full` | 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) | | `vcs.revision_delta.direction` | 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. --- diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md index 46bbd563c3..81db6b6675 100644 --- a/docs/cicd/cicd-metrics.md +++ b/docs/cicd/cicd-metrics.md @@ -20,6 +20,7 @@ linkTitle: CICD metrics - [Metric: `vcs.change.count`](#metric-vcschangecount) - [Metric: `vcs.change.duration`](#metric-vcschangeduration) - [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.ref.count`](#metric-vcsrefcount) - [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 | |---|---|---|---|---|---| | [`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.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.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.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.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. -**[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 the same backends. @@ -407,21 +411,126 @@ This metric is [recommended][MetricRecommended]. | 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 | |---|---|---|---|---|---| -| [`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.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.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.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.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. -**[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 +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. + + + + + + +### Metric: `vcs.change.time_to_merge` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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. + @@ -440,7 +549,7 @@ This metric is [recommended][MetricRecommended]. | 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) | @@ -460,7 +569,7 @@ This metric is [recommended][MetricRecommended]. | 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 | |---|---|---|---|---|---| @@ -502,7 +611,7 @@ This metric is [recommended][MetricRecommended]. | 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, 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 | |---|---|---|---|---|---| | [`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.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.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.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.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.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. [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. [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. [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. [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.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. -**[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 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 | |---|---|---|---|---|---| -| [`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.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.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.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.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.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. [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. [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. [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. [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.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. -**[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 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 | |---|---|---|---|---|---| -| [`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.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.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.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.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. [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. [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. [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. -**[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 the same backends. diff --git a/model/vcs/metrics.yaml b/model/vcs/metrics.yaml index 9bb3118942..bec7f48fde 100644 --- a/model/vcs/metrics.yaml +++ b/model/vcs/metrics.yaml @@ -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)' instrument: updowncounter unit: "{change}" - stability: experimental + stability: development attributes: - ref: vcs.change.state 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.' instrument: gauge unit: "s" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -32,10 +32,10 @@ groups: - id: metric.vcs.change.time_to_approval type: metric 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 unit: "s" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -43,21 +43,47 @@ groups: 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.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 type: metric metric_name: vcs.repository.count - brief: 'The number of repositories in an organization' + brief: 'The number of repositories in an organization.' instrument: updowncounter unit: "{repository}" - stability: experimental + stability: development attributes: [] - id: metric.vcs.ref.count type: metric 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 unit: "{ref}" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -68,14 +94,14 @@ groups: - id: metric.vcs.ref.lines_delta type: metric 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: | This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). If number of lines added/removed should be calculated from the start of time, then `vcs.ref.base.name` SHOULD be set to an empty string. instrument: gauge unit: "{line}" - stability: experimental + stability: development attributes: - ref: vcs.change.id 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`. instrument: gauge unit: "{revision}" - stability: experimental + stability: development attributes: - ref: vcs.change.id 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`' instrument: gauge unit: "s" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required @@ -144,7 +170,7 @@ groups: brief: 'The number of unique contributors to a repository' instrument: gauge unit: "{contributor}" - stability: experimental + stability: development attributes: - ref: vcs.repository.url.full requirement_level: required diff --git a/model/vcs/registry.yaml b/model/vcs/registry.yaml index d9e96deb9e..476b2746f9 100644 --- a/model/vcs/registry.yaml +++ b/model/vcs/registry.yaml @@ -8,7 +8,7 @@ groups: attributes: - id: vcs.repository.url.full type: string - stability: experimental + stability: development brief: > 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 @@ -23,7 +23,7 @@ groups: ] - id: vcs.repository.name type: string - stability: experimental + stability: development brief: > The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization @@ -39,11 +39,15 @@ groups: ] - id: vcs.ref.base.name type: string - stability: experimental + stability: development brief: > The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **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"] - id: vcs.ref.base.type type: @@ -51,31 +55,39 @@ groups: - id: branch value: branch brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" - stability: experimental + stability: development - id: tag value: tag brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" - stability: experimental - stability: experimental + stability: development + stability: development brief: > 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"] - id: vcs.ref.base.revision type: string - stability: experimental + stability: development brief: > 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. 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 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. examples: [ "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", @@ -85,11 +97,14 @@ groups: ] - id: vcs.ref.head.name type: string - stability: experimental + stability: development brief: > The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **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"] - id: vcs.ref.head.type type: @@ -97,31 +112,36 @@ groups: - id: branch value: branch brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" - stability: experimental + stability: development - id: tag value: tag brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" - stability: experimental - stability: experimental + stability: development + stability: development brief: > 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"] - id: vcs.ref.head.revision type: string - stability: experimental + stability: development brief: > 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. 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 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. examples: [ "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", @@ -135,12 +155,12 @@ groups: - id: branch value: branch brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)" - stability: experimental + stability: development - id: tag value: tag brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)" - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. examples: ["branch", "tag"] @@ -150,12 +170,12 @@ groups: - id: behind value: behind brief: "How many revisions the change is behind the target ref." - stability: experimental + stability: development - id: ahead value: ahead brief: "How many revisions the change is ahead of the target ref." - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of revision comparison. examples: ["ahead", "behind"] @@ -165,18 +185,18 @@ groups: - id: added value: added brief: "How many lines were added." - stability: experimental + stability: development - id: removed value: removed brief: "How many lines were removed." - stability: experimental - stability: experimental + stability: development + stability: development brief: > The type of line change being measured on a branch or change. examples: ["added", "removed"] - id: vcs.change.title type: string - stability: experimental + stability: development brief: > 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 @@ -189,7 +209,7 @@ groups: ] - id: vcs.change.id type: string - stability: experimental + stability: development brief: > 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. @@ -200,22 +220,22 @@ groups: - id: 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." - stability: experimental + stability: development - id: 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." - stability: experimental + stability: development - id: closed value: closed brief: >- 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. - stability: experimental + stability: development - id: merged value: merged brief: "Merged indicates that the change has been successfully integrated into the target codebase." - stability: experimental - stability: experimental + stability: development + stability: development brief: > The state of the change (pull request/merge request/changelist). examples: ["open", "closed", "merged"]