From 1e20f5a2a2d7bb1bbcb1ce9375d57cdca07fde9f Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Sat, 14 Dec 2024 18:50:14 -0500 Subject: [PATCH 1/4] [vcs] add `vcs.change.time_to_merge` metric --- .chloggen/vcs-ttm.yaml | 22 ++++++++++++++++++++++ docs/cicd/cicd-metrics.md | 8 ++++---- model/vcs/metrics.yaml | 30 ++++++++++++++++++++++++++---- 3 files changed, 52 insertions(+), 8 deletions(-) create mode 100755 .chloggen/vcs-ttm.yaml diff --git a/.chloggen/vcs-ttm.yaml b/.chloggen/vcs-ttm.yaml new file mode 100755 index 0000000000..e7b7b47cf9 --- /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: [] + +# (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..4fa36a2345 100644 --- a/docs/cicd/cicd-metrics.md +++ b/docs/cicd/cicd-metrics.md @@ -132,7 +132,7 @@ 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 | |---|---|---|---|---|---| @@ -165,7 +165,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 +185,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 +227,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..2158be3590 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,32 @@ groups: requirement_level: recommended - ref: vcs.ref.head.name requirement_level: required + - 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.base.name + requirement_level: recommended + - ref: vcs.ref.base.revision + requirement_level: recommended + - ref: vcs.ref.head.name + requirement_level: recommended + - ref: vcs.ref.head.revision + requirement_level: recommended - 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 +76,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 +90,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). From de2096e9c6f858206837fea9ba90b90bfacf6e0e Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Sat, 14 Dec 2024 18:53:48 -0500 Subject: [PATCH 2/4] [chore] update changelog with number --- .chloggen/vcs-ttm.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.chloggen/vcs-ttm.yaml b/.chloggen/vcs-ttm.yaml index e7b7b47cf9..25f2671a70 100755 --- a/.chloggen/vcs-ttm.yaml +++ b/.chloggen/vcs-ttm.yaml @@ -14,7 +14,7 @@ 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: [] +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. From ee75ecb62546127eecaee88bf72921bc5e5af9c8 Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Sat, 14 Dec 2024 18:56:53 -0500 Subject: [PATCH 3/4] [cgore] fixes --- model/vcs/metrics.yaml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/model/vcs/metrics.yaml b/model/vcs/metrics.yaml index 2158be3590..854ea165cf 100644 --- a/model/vcs/metrics.yaml +++ b/model/vcs/metrics.yaml @@ -57,14 +57,12 @@ groups: requirement_level: recommended - ref: vcs.ref.head.name requirement_level: required + - ref: vcs.ref.head.revision + requirement_level: recommended - ref: vcs.ref.base.name requirement_level: recommended - ref: vcs.ref.base.revision requirement_level: recommended - - ref: vcs.ref.head.name - requirement_level: recommended - - ref: vcs.ref.head.revision - requirement_level: recommended - id: metric.vcs.repository.count type: metric metric_name: vcs.repository.count From 8107854f1d6a871c8736d8cc9a189da010e1fecc Mon Sep 17 00:00:00 2001 From: Adriel Perkins Date: Wed, 18 Dec 2024 09:55:32 -0500 Subject: [PATCH 4/4] [chore] update attributes of time to approval --- docs/cicd/cicd-metrics.md | 27 +++++++++++++++++++++++++-- model/vcs/metrics.yaml | 6 ++++++ 2 files changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md index 4fa36a2345..bfa30a246d 100644 --- a/docs/cicd/cicd-metrics.md +++ b/docs/cicd/cicd-metrics.md @@ -138,12 +138,35 @@ This metric is [recommended][MetricRecommended]. |---|---|---|---|---|---| | [`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.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.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. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `Recommended` | ![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. [3] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | `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 the `.git` extension. -**[2] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same +**[2] `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. + +**[3] `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. + +**[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 854ea165cf..f3d268c784 100644 --- a/model/vcs/metrics.yaml +++ b/model/vcs/metrics.yaml @@ -43,6 +43,12 @@ groups: requirement_level: recommended - ref: vcs.ref.head.name requirement_level: required + - ref: vcs.ref.head.revision + requirement_level: recommended + - ref: vcs.ref.base.name + requirement_level: recommended + - ref: vcs.ref.base.revision + requirement_level: recommended - id: metric.vcs.change.time_to_merge type: metric metric_name: vcs.change.time_to_merge