[vcs] Adds vcs.repository.name attribute and updates `vcs.repositor…

…y.url.full` to be represented consistently. (#1608) Co-authored-by: Liudmila Molkova <[email protected]> Co-authored-by: Trask Stalnaker <[email protected]>
open-telemetry · Dec 3, 2024 · c8024bf · c8024bf
1 parent c2f983d
commit c8024bf
Show file tree

Hide file tree

Showing 5 changed files with 144 additions and 12 deletions.
diff --git a/.chloggen/vcs-1254.yaml b/.chloggen/vcs-1254.yaml
@@ -0,0 +1,25 @@
+# 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: |
+  Adds `vcs.repository.name` attribute to registry and update
+  `vcs.repository.url.full` description for consistent representation. Updates
+  the VCS metrics to include `vcs.repository.name` as a recommended attribute.
+
+# 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: [1254, 1453]
+
+# (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
@@ -26,7 +26,8 @@ This group defines the attributes for [Version Control Systems (VCS)](https://wi
 | <a id="vcs-ref-head-revision" href="#vcs-ref-head-revision">`vcs.ref.head.revision`</a> | string | The revision, literally [revised version](https://www.merriam-webster.com/dictionary/revision), The revision most often refers to a commit object in Git, or a revision number in SVN. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="vcs-ref-head-type" href="#vcs-ref-head-type">`vcs.ref.head.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="vcs-ref-type" href="#vcs-ref-type">`vcs.ref.type`</a> | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="vcs-repository-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) |
+| <a id="vcs-repository-name" href="#vcs-repository-name">`vcs.repository.name`</a> | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [3] | `semantic-conventions`; `my-cool-repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="vcs-repository-url-full" href="#vcs-repository-url-full">`vcs.repository.url.full`</a> | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851?hl=en#:~:text=A%20canonical%20URL%20is%20the,Google%20chooses%20one%20as%20canonical.) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [4] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="vcs-revision-delta-direction" href="#vcs-revision-delta-direction">`vcs.revision_delta.direction`</a> | string | The type of revision comparison. | `ahead`; `behind` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 **[1] `vcs.ref.base.revision`:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf),
@@ -49,6 +50,13 @@ 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.
 
+**[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.
+
+**[4] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include
+the `.git` extension.
+
 ---
 
 `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.