diff --git a/.chloggen/1372-vcs-metrics.yaml b/.chloggen/1372-vcs-metrics.yaml new file mode 100644 index 0000000000..5c9faded46 --- /dev/null +++ b/.chloggen/1372-vcs-metrics.yaml @@ -0,0 +1,31 @@ +# 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 inspired by 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: | + Makes the following changes: + + - Add metrics `vcs.change.count`, `vcs.change.duration`, `vcs.change.time_to_approval`, `vcs.repository.count`, `vcs.ref.count`, + `vcs.ref.lines_delta`, `vcs.ref.revisions_delta`, `vcs.ref.time`, `vcs.contributor.count` + - The VCS attributes `vcs.change.state`, `vcs.revision_delta.direction` and `vcs.line_change.type` have been added to the registry. + - The VCS ref attributes have been duplicated to `vcs.ref.base.*` to allow for ref comparisons. + - The VCS attribute `vcs.ref.type` has been added for simplicity when neither a full head or base ref is necessary. + - `vcs.repository.change.*` attributes have been deprecated and moved to `vcs.change.*`. + - `vcs.repository.ref.*` attributes have been deprecated and moved to `vcs.ref.head.*`. diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index a4307b0262..c0858bd806 100644 --- a/.github/CODEOWNERS +++ b/.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 diff --git a/docs/README.md b/docs/README.md index f31cc91fa5..37a3e92c49 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/attributes-registry/vcs.md b/docs/attributes-registry/vcs.md index 82ed2adf9f..15fc8f3f4e 100644 --- a/docs/attributes-registry/vcs.md +++ b/docs/attributes-registry/vcs.md @@ -6,18 +6,28 @@ # VCS +- [VCS Repository Attributes](#vcs-repository-attributes) +- [VCS Deprecated Attributes](#vcs-deprecated-attributes) + ## VCS Repository Attributes This group defines the attributes for [Version Control Systems (VCS)](https://wikipedia.org/wiki/Version_control). | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `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.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) | +| `vcs.change.id` | 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) | +| `vcs.change.state` | string | The state of the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.change.title` | 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) | +| `vcs.line_change.type` | string | The type of line change being measured on a branch or change. | `added`; `removed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.base.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.ref.base.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.ref.base.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) | +| `vcs.ref.head.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.ref.head.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. [2] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `vcs.ref.head.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) | +| `vcs.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) | | `vcs.repository.url.full` | 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) | +| `vcs.revision_delta.direction` | string | The type of revision comparison. | `ahead`; `behind` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), of the recorded change to a ref within a repository pointing to a @@ -25,10 +35,76 @@ commit [commit](https://git-scm.com/docs/git-commit) object. It does not necessarily have to be a hash; it can simply define a [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where -it is identical to the `ref.name`, it SHOULD still be included. It is +it is identical to the `ref.base.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. +**[2]:** The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), +of the recorded change to a ref within a repository pointing to a +commit [commit](https://git-scm.com/docs/git-commit) object. It does +not necessarily have to be a hash; it can simply define a +[revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) +which is an integer that is monotonically increasing. In cases where +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. + +`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 | +|---|---|---| +| `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) | +| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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) | +| `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) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `added` | How many lines were added. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `removed` | How many lines were removed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `ahead` | How many revisions the change is ahead of the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `behind` | How many revisions the change is behind the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +## VCS Deprecated Attributes + +"Describes deprecated vcs attributes." + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `vcs.repository.change.id` | string | Deprecated, use `vcs.change.id` instead. | `123` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.change.id` instead. | +| `vcs.repository.change.title` | 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)
Deprecated, use `vcs.change.title` instead. | +| `vcs.repository.ref.name` | string | Deprecated, use `vcs.ref.head.name` instead. | `my-feature-branch`; `tag-1-test` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.ref.head.name` instead. | +| `vcs.repository.ref.revision` | string | Deprecated, use `vcs.ref.head.revision` instead. | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.ref.head.revision` instead. | +| `vcs.repository.ref.type` | string | Deprecated, use `vcs.ref.head.type` instead. | `branch`; `tag` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Deprecated, use `vcs.ref.head.type` instead. | + `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..a0b3244681 --- /dev/null +++ b/docs/cicd/cicd-metrics.md @@ -0,0 +1,347 @@ + + +# Semantic Conventions for CICD Metrics + +**Status**: [Experimental][DocumentStatus] + + + + + +- [VCS Metrics](#vcs-metrics) + - [Metric: `vcs.change.count`](#metric-vcschangecount) + - [Metric: `vcs.change.duration`](#metric-vcschangeduration) + - [Metric: `vcs.change.time_to_approval`](#metric-vcschangetime_to_approval) + - [Metric: `vcs.repository.count`](#metric-vcsrepositorycount) + - [Metric: `vcs.ref.count`](#metric-vcsrefcount) + - [Metric: `vcs.ref.lines_delta`](#metric-vcsreflines_delta) + - [Metric: `vcs.ref.revisions_delta`](#metric-vcsrefrevisions_delta) + - [Metric: `vcs.ref.time`](#metric-vcsreftime) + - [Metric: `vcs.contributor.count`](#metric-vcscontributorcount) + + + +## VCS Metrics + +The conventions described in this section are specific to Version Control Systems. + +**Disclaimer:** These are initial VCS metrics and attributes +but more may be added in the future. + +### Metric: `vcs.change.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.change.count` | UpDownCounter | `{change}` | The number of changes (pull requests/merge requests/changelists) in a repository, categorized by their state (e.g. 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 the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `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 | +|---|---|---| +| `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) | +| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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) | +| `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) | + + + + + + +### Metric: `vcs.change.duration` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.change.duration` | Gauge | `s` | The time duration a change (pull request/merge request/changelist) has been in a given state. | ![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 the change (pull request/merge request/changelist). | `open`; `closed`; `merged` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `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 | +|---|---|---| +| `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) | +| `merged` | Merged indicates that the change has been successfully integrated into the target codebase. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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) | +| `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) | + + + + + + +### Metric: `vcs.change.time_to_approval` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.change.time_to_approval` | Gauge | `s` | The amount of time since its creation it took a change (pull request/merge request/changelist) to get the first approval | ![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.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.repository.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.repository.count` | UpDownCounter | `{repository}` | The number of repositories in an organization | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.ref.count` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.count` | UpDownCounter | `{ref}` | The number of refs of type branch or tag in a repository | ![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.ref.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.ref.lines_delta` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.lines_delta` | Gauge | `{line}` | The number of lines added/removed in a ref (branch) relative to the ref from the `vcs.ref.base.name` attribute [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, +instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). +If number of lines added/removed should be calculated from the start of time, then `vcs.ref.base.name` SHOULD be set to an empty string. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.line_change.type`](/docs/attributes-registry/vcs.md) | string | The type of line change being measured on a branch or change. | `added`; `removed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | 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` | `Conditionally Required` if a change is associate with the ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `added` | How many lines were added. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `removed` | How many lines were removed. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.ref.revisions_delta` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.revisions_delta` | Gauge | `{revision}` | The number of revisions (commits) a ref (branch) is ahead/behind the branch from the `vcs.ref.base.name` attribute [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1]:** This metric should be reported for each `vcs.revision_delta.direction` value. For example if branch `a` is 3 commits behind and 2 commits ahead of `trunk`, +instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`. + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`vcs.ref.base.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.base.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.revision_delta.direction`](/docs/attributes-registry/vcs.md) | string | The type of revision comparison. | `ahead`; `behind` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.change.id`](/docs/attributes-registry/vcs.md) | 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` | `Conditionally Required` if a change is associate with the ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `ahead` | How many revisions the change is ahead of the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `behind` | How many revisions the change is behind the target ref. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.ref.time` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.ref.time` | Gauge | `s` | Time a ref (branch) created from the default branch (trunk) has existed. The `ref.type` attribute will always be `branch` | ![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.ref.head.name`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.ref.head.type`](/docs/attributes-registry/vcs.md) | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`vcs.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +`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. + +| Value | Description | Stability | +|---|---|---| +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +### Metric: `vcs.contributor.count` + +This metric is [opt-in][MetricOptIn]. + + + + + + + + +| Name | Instrument Type | Unit (UCUM) | Description | Stability | +| -------- | --------------- | ----------- | -------------- | --------- | +| `vcs.contributor.count` | Gauge | `{contributor}` | The number of unique contributors to a repository | ![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.repository.url.full`](/docs/attributes-registry/vcs.md) | 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` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status +[MetricOptIn]: /docs/general/metric-requirement-level.md#opt-in +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/model/vcs/deprecated/registry-deprecated.yaml b/model/vcs/deprecated/registry-deprecated.yaml new file mode 100644 index 0000000000..80ac9b8768 --- /dev/null +++ b/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.head.name` instead.' + brief: > + Deprecated, use `vcs.ref.head.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.head.type` instead.' + brief: > + Deprecated, use `vcs.ref.head.type` instead. + examples: ["branch", "tag"] + - id: vcs.repository.ref.revision + type: string + stability: experimental + deprecated: 'Deprecated, use `vcs.ref.head.revision` instead.' + brief: > + Deprecated, use `vcs.ref.head.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"] diff --git a/model/vcs/metrics.yaml b/model/vcs/metrics.yaml new file mode 100644 index 0000000000..e2e72f115f --- /dev/null +++ b/model/vcs/metrics.yaml @@ -0,0 +1,136 @@ +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.head.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 since its creation it took a change (pull request/merge request/changelist) to get the first approval' + instrument: gauge + unit: "s" + stability: experimental + attributes: + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.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.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 ref from the `vcs.ref.base.name` attribute' + note: | + This metric should be reported for each `vcs.line_change.type` value. For example if a ref added 3 lines and removed 2 lines, + instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers). + If number of lines added/removed should be calculated from the start of time, then `vcs.ref.base.name` SHOULD be set to an empty string. + instrument: gauge + unit: "{line}" + stability: experimental + attributes: + - ref: vcs.change.id + requirement_level: + conditionally_required: if a change is associate with the ref. + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.name + requirement_level: required + - ref: vcs.ref.head.type + requirement_level: required + - ref: vcs.ref.base.name + requirement_level: required + - ref: vcs.ref.base.type + requirement_level: required + - ref: vcs.line_change.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 branch from the `vcs.ref.base.name` attribute' + note: | + This metric should be reported for each `vcs.revision_delta.direction` value. For example if branch `a` is 3 commits behind and 2 commits ahead of `trunk`, + instrumentation SHOULD report two measurements: 3 and 2 (both positive numbers) and `vcs.ref.base.name` is set to `trunk`. + instrument: gauge + unit: "{revision}" + stability: experimental + attributes: + - ref: vcs.change.id + requirement_level: + conditionally_required: if a change is associate with the ref. + - ref: vcs.repository.url.full + requirement_level: required + - ref: vcs.ref.head.name + requirement_level: required + - ref: vcs.ref.head.type + requirement_level: required + - ref: vcs.ref.base.name + requirement_level: required + - ref: vcs.ref.base.type + requirement_level: required + - ref: vcs.revision_delta.direction + 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.head.name + requirement_level: required + - ref: vcs.ref.head.type + requirement_level: required + - id: metric.vcs.contributor.count + type: metric + metric_name: vcs.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 diff --git a/model/vcs/registry.yaml b/model/vcs/registry.yaml index 2a0dec19d1..afe703ac53 100644 --- a/model/vcs/registry.yaml +++ b/model/vcs/registry.yaml @@ -17,7 +17,7 @@ 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.base.name type: string stability: experimental brief: > @@ -25,7 +25,7 @@ groups: [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.base.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.base.revision type: string stability: experimental brief: > @@ -53,7 +53,7 @@ groups: not necessarily have to be a hash; it can simply define a [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) which is an integer that is monotonically increasing. In cases where - it is identical to the `ref.name`, it SHOULD still be included. It is + it is identical to the `ref.base.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. examples: @@ -63,11 +63,102 @@ groups: "123", "HEAD", ] - - id: vcs.repository.change.title + - id: vcs.ref.head.name type: string stability: experimental brief: > - The human readable title of the change (pull request/merge request). + 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.ref.head.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 + brief: > + The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. + examples: ["branch", "tag"] + - id: vcs.ref.head.revision + type: string + stability: experimental + brief: > + 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. + note: | + The revision can be a full [hash value (see glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), + of the recorded change to a ref within a repository pointing to a + commit [commit](https://git-scm.com/docs/git-commit) object. It does + not necessarily have to be a hash; it can simply define a + [revision number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) + which is an integer that is monotonically increasing. In cases where + 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. + examples: + [ + "9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc", + "main", + "123", + "HEAD", + ] + - id: vcs.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 + brief: > + The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. + examples: ["branch", "tag"] + - id: vcs.revision_delta.direction + 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/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 +167,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"] diff --git a/schema-next.yaml b/schema-next.yaml index a3faafd93f..5439843483 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -8,6 +8,14 @@ versions: - rename_attributes: attribute_map: process.executable.build_id.profiling: process.executable.build_id.htlhash + # 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.head.name + vcs.repository.ref.revision: vcs.ref.head.revision + vcs.repository.ref.type: vcs.ref.head.type metrics: changes: # https://github.com/open-telemetry/semantic-conventions/pull/1492