Add VCS metrics from Github receiver

.chloggen/1372-vcs-metrics.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: breaking
+
+# 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 the VCS metrics from the GitHub Receiver
+
+# 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: [1372]
+
+# (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: |
+  - The VCS attribute `vcs.change.state` has been added to the registry.
+  - `vcs.repository.change.*` attributes have been deprecated and moved to `vcs.change.*`.
+  - `vcs.repository.ref.*` attributes have been deprecated and moved to `vcs.ref.*`.

.github/CODEOWNERS

@@ -81,6 +81,7 @@
 /model/user/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-security-approvers
 
 # CICD semantic conventions
+/docs/cicd/                       @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
 /model/artifact/                  @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
 /model/cicd/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers
 /model/code/                      @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-cicd-approvers

docs/README.md

@@ -21,6 +21,7 @@ The benefit to using Semantic Conventions is in following a common naming scheme
 Semantic Conventions are defined for the following areas:
 
 * **[General](general/README.md): General Semantic Conventions**.
+* [CICD](cicd/cicd-metrics.md): Semantic Conventions for CICD systems.
 * [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries.
 * [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
 * [Database](database/README.md): Semantic Conventions for database operations.

model/vcs/deprecated/registry-deprecated.yaml

@@ -0,0 +1,61 @@
+groups:
+  - id: registry.vcs.deprecated
+    type: attribute_group
+    brief: >
+      "Describes deprecated vcs attributes."
+    attributes:
+      - id: vcs.repository.ref.name
+        type: string
+        stability: experimental
+        deprecated: 'Deprecated, use `vcs.ref.name` instead.'
+        brief: >
+          Deprecated, use `vcs.ref.name` instead.
+        examples: ["my-feature-branch", "tag-1-test"]
+      - id: vcs.repository.ref.type
+        type:
+          members:
+            - id: branch
+              value: branch
+              brief: "[branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
+              stability: experimental
+            - id: tag
+              value: tag
+              brief: "[tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
+              stability: experimental
+        stability: experimental
+        deprecated: 'Deprecated, use `vcs.ref.type` instead.'
+        brief: >
+          Deprecated, use `vcs.ref.type` instead.
+        examples: ["branch", "tag"]
+      - id: vcs.repository.ref.revision
+        type: string
+        stability: experimental
+        deprecated: 'Deprecated, use `vcs.ref.revision` instead.'
+        brief: >
+          Deprecated, use `vcs.ref.revision` instead.
+        examples:
+          [
+            "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc",
+            "main",
+            "123",
+            "HEAD",
+          ]
+      - id: vcs.repository.change.title
+        type: string
+        stability: experimental
+        deprecated: 'Deprecated, use `vcs.change.title` instead.'
+        brief: >
+          Deprecated, use `vcs.change.title` instead.
+        examples:
+          [
+            "Fixes broken thing",
+            "feat: add my new feature",
+            "[chore] update dependency",
+          ]
+      - id: vcs.repository.change.id
+        type: string
+        stability: experimental
+        deprecated: 'Deprecated, use `vcs.change.id` instead.'
+        brief: >
+          Deprecated, use `vcs.change.id` instead.
+        examples: ["123"]

model/vcs/metrics.yaml

@@ -0,0 +1,147 @@
+groups:
+  - id: metric.vcs.change.count
+    type: metric
+    metric_name: vcs.change.count
+    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
+    attributes:
+      - ref: vcs.change.state
+        requirement_level: required
+      - ref: vcs.repository.url.full
+        requirement_level: required
+  - id: metric.vcs.change.duration
+    type: metric
+    metric_name: vcs.change.duration
+    brief: 'The time duration a change (pull request/merge request/changelist) has been in a given state.'
+    instrument: gauge
+    unit: "s"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.name
+        requirement_level: required
+      - ref: vcs.change.state
+        requirement_level: required
+  - id: metric.vcs.change.time_to_approval
+    type: metric
+    metric_name: vcs.change.time_to_approval
+    brief: 'The amount of time it took a change (pull request/merge request/changelist) to go from open to approved'
+    instrument: gauge
+    unit: "s"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.name
+        requirement_level: required
+  - id: metric.vcs.repository.count
+    type: metric
+    metric_name: vcs.repository.count
+    brief: 'The number of repositories in an organization'
+    instrument: updowncounter
+    unit: "{repository}"
+    stability: experimental
+    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'
+    instrument: updowncounter
+    unit: "{ref}"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.type
+        requirement_level: required
+  - id: metric.vcs.change.lines_delta
+    type: metric
+    metric_name: vcs.change.lines_delta
+    brief: 'The number of lines added/removed in a change relative to the target branch of the change'
+    instrument: gauge
+    unit: "{line}"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.name
+        requirement_level: required
+      - ref: vcs.ref.type
+        requirement_level: required
+      - ref: vcs.line_change.type
+        requirement_level: required
+  - 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 previous day'
+    instrument: gauge
+    unit: "{line}"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.name
+        requirement_level: required
+      - ref: vcs.ref.type
+        requirement_level: required
+      - ref: vcs.line_change.type
+        requirement_level: required
+  - id: metric.vcs.change.revisions_delta
+    type: metric
+    metric_name: vcs.change.revisions_delta
+    brief: 'The number of revisions (commits) a change is ahead/behind the target branch of the change'
+    instrument: gauge
+    unit: "{revision}"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.name
+        requirement_level: required
+      - ref: vcs.ref.type
+        requirement_level: required
+      - ref: vcs.revision_delta.type
+        requirement_level: required
+  - id: metric.vcs.ref.revisions_delta
+    type: metric
+    metric_name: vcs.ref.revisions_delta
+    brief: 'The number of revisions (commits) a ref (branch) is ahead/behind the default branch (trunk)'
+    instrument: gauge
+    unit: "{revision}"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.name
+        requirement_level: required
+      - ref: vcs.ref.type
+        requirement_level: required
+      - ref: vcs.revision_delta.type
+        requirement_level: required
+  - id: metric.vcs.ref.time
+    type: metric
+    metric_name: vcs.ref.time
+    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
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required
+      - ref: vcs.ref.name
+        requirement_level: required
+      - ref: vcs.ref.type
+        requirement_level: required
+  - id: metric.vcs.repository.contributor.count
+    type: metric
+    metric_name: vcs.repository.contributor.count
+    brief: 'The number of unique contributors to a repository'
+    instrument: gauge
+    unit: "{contributor}"
+    stability: experimental
+    attributes:
+      - ref: vcs.repository.url.full
+        requirement_level: required

model/vcs/registry.yaml

@@ -17,15 +17,15 @@ groups:
             "https://github.com/opentelemetry/open-telemetry-collector-contrib",
             "https://gitlab.com/my-org/my-project/my-projects-project/repo",
           ]
-      - id: vcs.repository.ref.name
+      - id: vcs.ref.name
         type: string
         stability: experimental
         brief: >
           The name of the
           [reference](https://git-scm.com/docs/gitglossary#def_ref) such as
           **branch** or **tag** in the repository.
         examples: ["my-feature-branch", "tag-1-test"]
-      - id: vcs.repository.ref.type
+      - id: vcs.ref.type
         type:
           members:
             - id: branch
@@ -40,7 +40,7 @@ groups:
         brief: >
           The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository.
         examples: ["branch", "tag"]
-      - id: vcs.repository.ref.revision
+      - id: vcs.ref.revision
         type: string
         stability: experimental
         brief: >
@@ -63,11 +63,41 @@ groups:
             "123",
             "HEAD",
           ]
-      - id: vcs.repository.change.title
+      - id: vcs.revision_delta.type
+        type:
+          members:
+            - id: behind
+              value: behind
+              brief: "How many revisions the change is behind the target ref."
+              stability: experimental
+            - id: ahead
+              value: ahead
+              brief: "How many revisions the change is ahead of the target ref."
+              stability: experimental
+        stability: experimental
+        brief: >
+          The type of revision comparison.
+        examples: ["ahead", "behind"]
+      - id: vcs.line_change.type
+        type:
+          members:
+            - id: added
+              value: added
+              brief: "How many lines were added."
+              stability: experimental
+            - id: removed
+              value: removed
+              brief: "How many lines were removed."
+              stability: experimental
+        stability: experimental
+        brief: >
+          The type of line change being measured on a branch or change.
+        examples: ["added", "removed"]
+      - id: vcs.change.title
         type: string
         stability: experimental
         brief: >
-          The human readable title of the change (pull request/merge request).
+          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.
         examples:
@@ -76,10 +106,35 @@ groups:
             "feat: add my new feature",
             "[chore] update dependency",
           ]
-      - id: vcs.repository.change.id
+      - id: vcs.change.id
         type: string
         stability: experimental
         brief: >
-          The ID of the change (pull request/merge request) if applicable. This
+          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.
         examples: ["123"]
+      - id: vcs.change.state
+        type:
+          members:
+            - 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
+            - 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
+            - 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
+            - id: merged
+              value: merged
+              brief: "Merged indicates that the change has been successfully integrated into the target codebase."
+              stability: experimental
+        stability: experimental
+        brief: >
+          The state of the change (pull request/merge request/changelist).
+        examples: ["open", "closed", "merged"]

schema-next.yaml

@@ -2,6 +2,16 @@ file_format: 1.1.0
 schema_url: https://opentelemetry.io/schemas/next
 versions:
   next:
+    all:
+      changes:
+        # https://github.com/open-telemetry/semantic-conventions/pull/1383
+        - rename_attributes:
+            attribute_map:
+              vcs.repository.change.id: vcs.change.id
+              vcs.repository.change.title: vcs.change.title
+              vcs.repository.ref.name: vcs.ref.name
+              vcs.repository.ref.revision: vcs.ref.revision
+              vcs.repository.ref.type: vcs.ref.type
   1.28.0:
     metrics:
       changes: