diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md index 0e11f9b2bf..5c156cb05c 100644 --- 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 new file mode 100644 index 0000000000..7b7cf20fc9 --- /dev/null +++ b/docs/cicd/cicd-metrics.md @@ -0,0 +1,72 @@ + + +# Semantic Conventions for CICD Metrics + +**Status**: [Experimental][DocumentStatus] + + + + + +- [CICD Metrics](#cicd-metrics) + - [Metric: `vsc.repository.change.count`](#metric-vscrepositorychangecount) + + + +## 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` + + + + + + + + + + +| 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) | + + + + + + + + + + + + + + +| 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) | + + + + + + + diff --git a/model/metrics/vcs.yaml b/model/metrics/vcs.yaml new file mode 100644 index 0000000000..1e9740487a --- /dev/null +++ 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 index 150bf591ad..c68accd8ad 100644 --- 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"]