[cicd] add first cicd metric to registry, created cicd-metrics doc

open-telemetry · Sep 3, 2024 · 44a1c81 · 44a1c81
1 parent 11f5d37
commit 44a1c81
Show file tree

Hide file tree

Showing 4 changed files with 121 additions and 0 deletions.
diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md
@@ -12,8 +12,10 @@ This group defines the attributes for [Version Control Systems (VCS)](https://en
 
 | Attribute                     | Type   | Description                                                                                                                                                                                | Examples                                                                                                                             | Stability                                                        |
 | ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `vcs.change.state`            | string | The state of a change (pull request).                                                                                                                                                      | `open`; `merged`                                                                                                                     | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `vcs.repository.change.id`    | 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) |
 | `vcs.repository.change.title` | 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) |
+| `vcs.repository.name`         | string | The name of the repository.                                                                                                                                                                | `open-telemetry-collector-contrib`; `opentelemetry/open-telemetry-collector-contrib`; `my-org/my-project/my-projects-project`        | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | `vcs.repository.ref.name`     | 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) |
 | `vcs.repository.ref.revision` | 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) |
 | `vcs.repository.ref.type`     | 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) |
@@ -29,6 +31,13 @@ it is identical to the `ref.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.
 
+`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.
+
+| Value    | Description                                                                                    | Stability                                                        |
+| -------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `merged` | [merged](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)     | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `open`   | [open](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
 `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.
 
 | Value    | Description                                                                                      | Stability                                                        |

diff --git a/docs/cicd/cicd-metrics.md b/docs/cicd/cicd-metrics.md
@@ -0,0 +1,72 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: CICD metrics
+--->
+
+# Semantic Conventions for CICD Metrics
+
+**Status**: [Experimental][DocumentStatus]
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [CICD Metrics](#cicd-metrics)
+  - [Metric: `vsc.repository.change.count`](#metric-vscrepositorychangecount)
+
+<!-- tocstop -->
+
+## CICD Metrics
+
+The conventions described in this section are specific to CICD
+applications.
+
+**Disclaimer:** These are initial CICD metrics and attributes
+but more may be added in the future.
+
+
+### Metric: `vsc.repository.change.count`
+
+
+
+<!-- semconv metric.vsc.repository.change.count(metric_table) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `vsc.repository.change.count` | Gauge | `{count}` | The number of changes (pull requests) in a repository, categorized by their state (either open or merged) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+<!-- semconv metric.vsc.repository.change.count -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`vcs.change.state`](/docs/attributes-registry/vcs.md) | string | The state of a change (pull request). | `open`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`vcs.repository.name`](/docs/attributes-registry/vcs.md) | string | The name of the repository. | `open-telemetry-collector-contrib`; `opentelemetry/open-telemetry-collector-contrib`; `my-org/my-project/my-projects-project` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`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.
+
+| Value  | Description | Stability |
+|---|---|---|
+| `merged` | [merged](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `open` | [open](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
diff --git a/model/metrics/vcs.yaml b/model/metrics/vcs.yaml
@@ -0,0 +1,14 @@
+groups:
+  - id: metric.vsc.repository.change.count
+    type: metric
+    metric_name: vsc.repository.change.count
+    brief: 'The number of changes (pull requests) in a repository, categorized by their state (either open or merged)'
+    instrument: gauge
+    unit: "{count}"
+    stability: experimental
+    #extends: metric_attributes.vcs
+    attributes:
+      - ref: vcs.change.state
+        requirement_level: required
+      - ref: vcs.repository.name
+        requirement_level: required
diff --git a/model/registry/vcs.yaml b/model/registry/vcs.yaml
@@ -5,6 +5,17 @@ groups:
       This group defines the attributes for
       [Version Control Systems (VCS)](https://en.wikipedia.org/wiki/Version_control).
     attributes:
+      - id: vcs.repository.name
+        type: string
+        stability: experimental
+        brief: >
+          The name of the repository.
+        examples:
+          [
+            "open-telemetry-collector-contrib",
+            "opentelemetry/open-telemetry-collector-contrib",
+            "my-org/my-project/my-projects-project",
+          ]
       - id: vcs.repository.url.full
         type: string
         stability: experimental
@@ -83,3 +94,18 @@ groups:
           The ID of the change (pull request/merge request) 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](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch)"
+              stability: experimental
+            - id: merged
+              value: merged
+              brief: "[merged](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag)"
+              stability: experimental
+        stability: experimental
+        brief: >
+          The state of a change (pull request).
+        examples: ["open", "merged"]