Skip to content

Commit 43f9e30

Browse files
christophe-kamphaus-jemmicchristophe-kamphaus-jemmic
authored
Add VCS metrics from Github receiver (open-telemetry#1383)
1 parent afa2bf8 commit 43f9e30

File tree

9 files changed

+791
-14
lines changed

9 files changed

+791
-14
lines changed

‎.chloggen/1372-vcs-metrics.yaml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Use this changelog template to create an entry for release notes.
2+
#
3+
# If your change doesn't affect end users you should instead start
4+
# your pull request title with [chore] or use the "Skip Changelog" label.
5+
6+
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
7+
change_type: breaking
8+
9+
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
10+
component: vcs
11+
12+
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
13+
note: Add the VCS metrics inspired by the GitHub Receiver
14+
15+
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
16+
# The values here must be integers.
17+
issues: [1372]
18+
19+
# (Optional) One or more lines of additional information to render under the primary note.
20+
# These lines will be padded with 2 spaces and then inserted directly into the document.
21+
# Use pipe (|) for multiline entries.
22+
subtext: |
23+
Makes the following changes:
24+
25+
- Add metrics `vcs.change.count`, `vcs.change.duration`, `vcs.change.time_to_approval`, `vcs.repository.count`, `vcs.ref.count`,
26+
`vcs.ref.lines_delta`, `vcs.ref.revisions_delta`, `vcs.ref.time`, `vcs.contributor.count`
27+
- The VCS attributes `vcs.change.state`, `vcs.revision_delta.direction` and `vcs.line_change.type` have been added to the registry.
28+
- The VCS ref attributes have been duplicated to `vcs.ref.base.*` to allow for ref comparisons.
29+
- The VCS attribute `vcs.ref.type` has been added for simplicity when neither a full head or base ref is necessary.
30+
- `vcs.repository.change.*` attributes have been deprecated and moved to `vcs.change.*`.
31+
- `vcs.repository.ref.*` attributes have been deprecated and moved to `vcs.ref.head.*`.

‎.github/CODEOWNERS

+1
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@
8181
/model/user/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
8282

8383
# CICD semantic conventions
84+
/docs/cicd/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
8485
/model/artifact/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
8586
/model/cicd/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
8687
/model/code/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers

‎docs/README.md

+1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ The benefit to using Semantic Conventions is in following a common naming scheme
2121
Semantic Conventions are defined for the following areas:
2222

2323
* **[General](general/README.md): General Semantic Conventions**.
24+
* [CICD](cicd/cicd-metrics.md): Semantic Conventions for CICD systems.
2425
* [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries.
2526
* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
2627
* [Database](database/README.md): Semantic Conventions for database operations.

‎docs/attributes-registry/vcs.md

+82-6
Original file line numberDiff line numberDiff line change
@@ -6,29 +6,105 @@
66

77
# VCS
88

9+
- [VCS Repository Attributes](#vcs-repository-attributes)
10+
- [VCS Deprecated Attributes](#vcs-deprecated-attributes)
11+
912
## VCS Repository Attributes
1013

1114
This group defines the attributes for [Version Control Systems (VCS)](https://wikipedia.org/wiki/Version_control).
1215

1316
| Attribute | Type | Description | Examples | Stability |
1417
|---|---|---|---|---|
15-
| <a id="vcs-repository-change-id" href="#vcs-repository-change-id">`vcs.repository.change.id`</a> | string | The ID of the change (pull request/merge request) if applicable. This is usually a unique (within repository) identifier generated by the VCS system. | `123` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
16-
| <a id="vcs-repository-change-title" href="#vcs-repository-change-title">`vcs.repository.change.title`</a> | string | The human readable title of the change (pull request/merge request). 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) |
17-
| <a id="vcs-repository-ref-name" href="#vcs-repository-ref-name">`vcs.repository.ref.name`</a> | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
18-
| <a id="vcs-repository-ref-revision" href="#vcs-repository-ref-revision">`vcs.repository.ref.revision`</a> | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [1] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
19-
| <a id="vcs-repository-ref-type" href="#vcs-repository-ref-type">`vcs.repository.ref.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
18+
| <a id="vcs-change-id" href="#vcs-change-id">`vcs.change.id`</a> | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
19+
| <a id="vcs-change-state" href="#vcs-change-state">`vcs.change.state`</a> | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
20+
| <a id="vcs-change-title" href="#vcs-change-title">`vcs.change.title`</a> | string | The human readable title of the change (pull request/merge request/changelist). This title is often a brief summary of the change and may get merged in to a ref as the commit summary. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
21+
| <a id="vcs-line-change-type" href="#vcs-line-change-type">`vcs.line_change.type`</a> | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
22+
| <a id="vcs-ref-base-name" href="#vcs-ref-base-name">`vcs.ref.base.name`</a> | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
23+
| <a id="vcs-ref-base-revision" href="#vcs-ref-base-revision">`vcs.ref.base.revision`</a> | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [1] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
24+
| <a id="vcs-ref-base-type" href="#vcs-ref-base-type">`vcs.ref.base.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
25+
| <a id="vcs-ref-head-name" href="#vcs-ref-head-name">`vcs.ref.head.name`</a> | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. | `my-feature-branch`; `tag-1-test` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
26+
| <a id="vcs-ref-head-revision" href="#vcs-ref-head-revision">`vcs.ref.head.revision`</a> | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
27+
| <a id="vcs-ref-head-type" href="#vcs-ref-head-type">`vcs.ref.head.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
28+
| <a id="vcs-ref-type" href="#vcs-ref-type">`vcs.ref.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
2029
| <a id="vcs-repository-url-full" href="#vcs-repository-url-full">`vcs.repository.url.full`</a> | string | The [URL](https://wikipedia.org/wiki/URL) of the repository providing the complete address in order to locate and identify the repository. | `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) |
30+
| <a id="vcs-revision-delta-direction" href="#vcs-revision-delta-direction">`vcs.revision_delta.direction`</a> | string | The type of revision comparison. | `ahead`; `behind` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
2131

2232
**[1]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
2333
of the recorded change to a ref within a repository pointing to a
2434
commit [commit](https://git-scm.com/docs/git-commit) object. It does
2535
not necessarily have to be a hash; it can simply define a
2636
[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html)
2737
which is an integer that is monotonically increasing. In cases where
28-
it is identical to the `ref.name`, it SHOULD still be included. It is
38+
it is identical to the `ref.base.name`, it SHOULD still be included. It is
2939
up to the implementer to decide which value to set as the revision
3040
based on the VCS system and situational context.
3141

42+
**[2]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
43+
of the recorded change to a ref within a repository pointing to a
44+
commit [commit](https://git-scm.com/docs/git-commit) object. It does
45+
not necessarily have to be a hash; it can simply define a
46+
[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html)
47+
which is an integer that is monotonically increasing. In cases where
48+
it is identical to the `ref.head.name`, it SHOULD still be included. It is
49+
up to the implementer to decide which value to set as the revision
50+
based on the VCS system and situational context.
51+
52+
`vcs.change.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
53+
54+
| Value | Description | Stability |
55+
|---|---|---|
56+
| `closed` | 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
57+
| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
58+
| `open` | 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
59+
| `wip` | 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. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
60+
61+
`vcs.line_change.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
62+
63+
| Value | Description | Stability |
64+
|---|---|---|
65+
| `added` | How many lines were added. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
66+
| `removed` | How many lines were removed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
67+
68+
`vcs.ref.base.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
69+
70+
| Value | Description | Stability |
71+
|---|---|---|
72+
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
73+
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
74+
75+
`vcs.ref.head.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
76+
77+
| Value | Description | Stability |
78+
|---|---|---|
79+
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
80+
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
81+
82+
`vcs.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
83+
84+
| Value | Description | Stability |
85+
|---|---|---|
86+
| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
87+
| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
88+
89+
`vcs.revision_delta.direction` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
90+
91+
| Value | Description | Stability |
92+
|---|---|---|
93+
| `ahead` | How many revisions the change is ahead of the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
94+
| `behind` | How many revisions the change is behind the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
95+
96+
## VCS Deprecated Attributes
97+
98+
"Describes deprecated vcs attributes."
99+
100+
| Attribute | Type | Description | Examples | Stability |
101+
|---|---|---|---|---|
102+
| <a id="vcs-repository-change-id" href="#vcs-repository-change-id">`vcs.repository.change.id`</a> | string | Deprecated, use `vcs.change.id` instead. | `123` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.change.id` instead. |
103+
| <a id="vcs-repository-change-title" href="#vcs-repository-change-title">`vcs.repository.change.title`</a> | string | Deprecated, use `vcs.change.title` instead. | `Fixes broken thing`; `feat: add my new feature`; `[chore] update dependency` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.change.title` instead. |
104+
| <a id="vcs-repository-ref-name" href="#vcs-repository-ref-name">`vcs.repository.ref.name`</a> | string | Deprecated, use `vcs.ref.head.name` instead. | `my-feature-branch`; `tag-1-test` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.ref.head.name` instead. |
105+
| <a id="vcs-repository-ref-revision" href="#vcs-repository-ref-revision">`vcs.repository.ref.revision`</a> | string | Deprecated, use `vcs.ref.head.revision` instead. | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.ref.head.revision` instead. |
106+
| <a id="vcs-repository-ref-type" href="#vcs-repository-ref-type">`vcs.repository.ref.type`</a> | string | Deprecated, use `vcs.ref.head.type` instead. | `branch`; `tag` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Deprecated, use `vcs.ref.head.type` instead. |
107+
32108
`vcs.repository.ref.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
33109

34110
| Value | Description | Stability |

0 commit comments

Comments
 (0)