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/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md index 687eb76e43..14f97539c8 100644 --- a/docs/cicd/cicd-metrics.md +++ b/docs/cicd/cicd-metrics.md @@ -14,6 +14,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) @@ -132,13 +133,16 @@ 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.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` | `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. [2] | `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. [3] | `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. [4] | `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 the `.git` extension. @@ -147,6 +151,82 @@ the `.git` extension. repository if collecting telemetry across multiple orgs or groups in the same backends. +**[3] `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), +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. + +**[4] `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), +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. | `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.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` | `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. [2] | `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. [3] | `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. [4] | `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 +the `.git` extension. + +**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +repository if collecting telemetry across multiple orgs or groups in +the same backends. + +**[3] `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), +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. + +**[4] `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), +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. + @@ -165,7 +245,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) | @@ -185,7 +265,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 | |---|---|---|---|---|---| @@ -227,7 +307,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). diff --git a/model/vcs/metrics.yaml b/model/vcs/metrics.yaml index 9bb3118942..86fb361d6a 100644 --- a/model/vcs/metrics.yaml +++ b/model/vcs/metrics.yaml @@ -32,7 +32,7 @@ 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 @@ -43,10 +43,36 @@ 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: experimental + 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 @@ -54,7 +80,7 @@ groups: - 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 @@ -68,7 +94,7 @@ 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).