|
| 1 | +<!--- Hugo front matter used to generate the website version of this page: |
| 2 | +linkTitle: Spans |
| 3 | +---> |
| 4 | + |
| 5 | +# Semantic conventions for VCS client spans |
| 6 | + |
| 7 | +**Status**: [Development][DocumentStatus] |
| 8 | + |
| 9 | +<!-- START doctoc --> |
| 10 | +<!-- END doctoc --> |
| 11 | + |
| 12 | +## VCS Spans |
| 13 | + |
| 14 | +The conventions described in this section are specific to Version Control Systems (VCS). |
| 15 | + |
| 16 | +### VCS client span |
| 17 | + |
| 18 | +<!-- semconv span.vcs.client --> |
| 19 | +<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. --> |
| 20 | +<!-- see templates/registry/markdown/snippet.md.j2 --> |
| 21 | +<!-- prettier-ignore-start --> |
| 22 | + |
| 23 | +**Status:**  |
| 24 | + |
| 25 | +This span describes a Version Control System (VCS) operation client. |
| 26 | + |
| 27 | +**Span name** MUST follow the overall [guidelines for span names](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#span). |
| 28 | + |
| 29 | +The span name SHOULD be `{vcs.action} {vcs.repository.name}`. |
| 30 | +If the repository name is not available, the span name SHOULD be `{vcs.action}`. |
| 31 | + |
| 32 | +**VCS Action Generic Mapping:** |
| 33 | +The canonical values of `vcs.action` map across both Distributed (DVCS) and Centralized (CVCS) Version Control Systems: |
| 34 | +* `clone`: Git `clone`, Mercurial `clone`, SVN `checkout` (initial copy), Perforce `clone`/`sync` (initial setup). |
| 35 | +* `fetch`: Git `fetch`, Mercurial `pull` (without update), Perforce `fetch`/`sync` (metadata only). |
| 36 | +* `pull`: Git `pull`, Mercurial `pull -u`, SVN `update`, Perforce `sync`. |
| 37 | +* `push`: Git `push`, Mercurial `push`, SVN `commit`, Perforce `push`/`submit`. |
| 38 | +* `checkout`: Git `checkout`/`switch`, SVN `switch`, Mercurial `update`, Perforce `switch`/`edit`. |
| 39 | + |
| 40 | +**Span Hierarchy:** |
| 41 | +When integrated into CI/CD pipelines, VCS spans SHOULD be modeled as child spans of the CI/CD pipeline task/step execution spans (e.g., a task span representing a "checkout code" step). |
| 42 | +Any underlying HTTP client or RPC spans representing the actual network communication with the VCS server/provider SHOULD be modeled as child spans of the VCS span. |
| 43 | + |
| 44 | +**Span kind** SHOULD be `CLIENT`. |
| 45 | + |
| 46 | +**Span status** SHOULD follow the [Recording Errors](/docs/general/recording-errors.md) document. |
| 47 | + |
| 48 | +**Attributes:** |
| 49 | + |
| 50 | +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | |
| 51 | +| --- | --- | --- | --- | --- | --- | |
| 52 | +| [`vcs.action`](/docs/registry/attributes/vcs.md) |  | `Required` | string | The type of action performed by a VCS operation. | `clone`; `fetch`; `pull`; `push`; `checkout` | |
| 53 | +| [`vcs.repository.name`](/docs/registry/attributes/vcs.md) |  | `Required` | string | The human readable name of the repository. It SHOULD NOT include any additional identifier like Group/SubGroup in GitLab or organization in GitHub. [1] | `semantic-conventions`; `my-cool-repo` | |
| 54 | +| [`error.type`](/docs/registry/attributes/error.md) |  | `Conditionally Required` If the VCS operation fails. | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | |
| 55 | +| [`server.address`](/docs/registry/attributes/server.md) |  | `Recommended` | string | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | |
| 56 | +| [`server.port`](/docs/registry/attributes/server.md) |  | `Recommended` | int | Server port number. [4] | `80`; `8080`; `443` | |
| 57 | +| [`vcs.ref.head.name`](/docs/registry/attributes/vcs.md) |  | `Recommended` | string | The name of the [reference](https://git-scm.com/docs/gitglossary#def_ref) such as **branch** or **tag** in the repository. [5] | `my-feature-branch`; `tag-1-test` | |
| 58 | +| [`vcs.ref.head.revision`](/docs/registry/attributes/vcs.md) |  | `Recommended` | 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. [6] | `9d59409acf479dfa0df1aa568182e43e43df8bbe28d60fcf2bc52e30068802cc`; `main`; `123`; `HEAD` | |
| 59 | +| [`vcs.ref.type`](/docs/registry/attributes/vcs.md) |  | `Recommended` | string | The type of the [reference](https://git-scm.com/docs/gitglossary#def_ref) in the repository. | `branch`; `tag` | |
| 60 | +| [`vcs.repository.url.full`](/docs/registry/attributes/vcs.md) |  | `Recommended` | string | The [canonical URL](https://support.google.com/webmasters/answer/10347851) of the repository providing the complete HTTP(S) address in order to locate and identify the repository through a browser. [7] | `https://github.com/opentelemetry/open-telemetry-collector-contrib`; `https://gitlab.com/my-org/my-project/my-projects-project/repo` | |
| 61 | + |
| 62 | +**[1] `vcs.repository.name`:** Due to it only being the name, it can clash with forks of the same |
| 63 | +repository if collecting telemetry across multiple orgs or groups in |
| 64 | +the same backends. |
| 65 | + |
| 66 | +**[2] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. |
| 67 | + |
| 68 | +When `error.type` is set to a type (e.g., an exception type), its |
| 69 | +canonical class name identifying the type within the artifact SHOULD be used. |
| 70 | + |
| 71 | +If the recorded error type is a wrapper that is not meaningful for |
| 72 | +failure classification, instrumentation MAY use the type of the inner |
| 73 | +error instead. For example, in Go, errors created with `fmt.Errorf` |
| 74 | +using `%w` MAY be unwrapped when the wrapper type does not help |
| 75 | +classify the failure. |
| 76 | + |
| 77 | +Instrumentations SHOULD document the list of errors they report. |
| 78 | + |
| 79 | +The cardinality of `error.type` within one instrumentation library SHOULD be low. |
| 80 | +Telemetry consumers that aggregate data from multiple instrumentation libraries and applications |
| 81 | +should be prepared for `error.type` to have high cardinality at query time when no |
| 82 | +additional filters are applied. |
| 83 | + |
| 84 | +If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. |
| 85 | + |
| 86 | +If a specific domain defines its own set of error identifiers (such as HTTP or RPC status codes), |
| 87 | +it's RECOMMENDED to: |
| 88 | + |
| 89 | +- Use a domain-specific attribute |
| 90 | +- Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. |
| 91 | + |
| 92 | +**[3] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. |
| 93 | + |
| 94 | +**[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. |
| 95 | + |
| 96 | +**[5] `vcs.ref.head.name`:** `head` refers to where you are right now; the current reference at a |
| 97 | +given time. |
| 98 | + |
| 99 | +**[6] `vcs.ref.head.revision`:** `head` refers to where you are right now; the current reference at a |
| 100 | +given time.The revision can be a full [hash value (see |
| 101 | +glossary)](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-5.pdf), |
| 102 | +of the recorded change to a ref within a repository pointing to a |
| 103 | +commit [commit](https://git-scm.com/docs/git-commit) object. It does |
| 104 | +not necessarily have to be a hash; it can simply define a [revision |
| 105 | +number](https://svnbook.red-bean.com/en/1.7/svn.tour.revs.specifiers.html) |
| 106 | +which is an integer that is monotonically increasing. In cases where |
| 107 | +it is identical to the `ref.head.name`, it SHOULD still be included. |
| 108 | +It is up to the implementer to decide which value to set as the |
| 109 | +revision based on the VCS system and situational context. |
| 110 | + |
| 111 | +**[7] `vcs.repository.url.full`:** In Git Version Control Systems, the canonical URL SHOULD NOT include |
| 112 | +the `.git` extension. |
| 113 | + |
| 114 | +--- |
| 115 | + |
| 116 | +`error.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. |
| 117 | + |
| 118 | +| Value | Description | Stability | |
| 119 | +| --- | --- | --- | |
| 120 | +| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | |
| 121 | + |
| 122 | +--- |
| 123 | + |
| 124 | +`vcs.action` 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. |
| 125 | + |
| 126 | +| Value | Description | Stability | |
| 127 | +| --- | --- | --- | |
| 128 | +| `checkout` | Checkout is the operation of switching branches, revisions, or paths in the local working directory. |  | |
| 129 | +| `clone` | Clone is the operation of creating a local copy of a remote repository. |  | |
| 130 | +| `fetch` | Fetch is the operation of downloading changes from a remote repository without updating the working directory. |  | |
| 131 | +| `pull` | Pull is the operation of fetching and integrating remote changes into the local working directory. |  | |
| 132 | +| `push` | Push is the operation of uploading local changes to a remote repository. |  | |
| 133 | + |
| 134 | +--- |
| 135 | + |
| 136 | +`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. |
| 137 | + |
| 138 | +| Value | Description | Stability | |
| 139 | +| --- | --- | --- | |
| 140 | +| `branch` | [branch](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbranchabranch) |  | |
| 141 | +| `tag` | [tag](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddeftagatag) |  | |
| 142 | + |
| 143 | +<!-- prettier-ignore-end --> |
| 144 | +<!-- END AUTOGENERATED TEXT --> |
| 145 | +<!-- endsemconv --> |
| 146 | + |
| 147 | +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status |
0 commit comments