-
Notifications
You must be signed in to change notification settings - Fork 182
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add conventions for CLI Spans (#1588)
Co-authored-by: Liudmila Molkova <[email protected]>
- Loading branch information
Showing
3 changed files
with
186 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # 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: 'new_component' | ||
|
|
||
| # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) | ||
| component: 'cli' | ||
|
|
||
| # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). | ||
| note: Define span describing CLI application execution | ||
|
|
||
| # 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: [1577] | ||
|
|
||
| # (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: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| linkTitle: CLI | ||
| ---> | ||
|
|
||
| # Semantic Conventions for CLI (Command Line Interface) programs | ||
|
|
||
| **Status**: [Experimental][DocumentStatus] | ||
|
|
||
| This document defines semantic conventions to apply when instrumenting CLI programs, both as a caller and as callee. This document is intended for short-lived programs that end their execution, i.e. not daemon or long running background tasks. | ||
|
|
||
| Span kind SHOULD be `INTERNAL` when the traced program is the callee or `CLIENT` when the caller is tracing another program. | ||
|
|
||
| The span name SHOULD be set to `{process.executable.name}`. | ||
| Instrumentations that have additional context about executed commands MAY use a different low-cardinality span name format and SHOULD document it. | ||
|
|
||
| Span status SHOULD be set to `Error` if `{process.exit.code}` is not 0. | ||
|
|
||
| <!-- TODO: context propagation https://github.com/open-telemetry/semantic-conventions/issues/1612 --> | ||
|
|
||
| ## Execution (callee) spans | ||
|
|
||
| <!-- semconv span.cli.internal --> | ||
| <!-- 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 | | ||
| |---|---|---|---|---|---| | ||
| | [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` |  | | ||
| | [`process.exit.code`](/docs/attributes-registry/process.md) | int | The exit code of the process. | `127` | `Required` |  | | ||
| | [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Required` |  | | ||
| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if process.exit.code is not 0 |  | | ||
| | [`process.command_args`](/docs/attributes-registry/process.md) | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `["cmd/otecol", "--config=config.yaml"]` | `Recommended` |  | | ||
| | [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Recommended` |  | | ||
|
|
||
| **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. | ||
|
|
||
| When `error.type` is set to a type (e.g., an exception type), its | ||
| canonical class name identifying the type within the artifact SHOULD be used. | ||
|
|
||
| Instrumentations SHOULD document the list of errors they report. | ||
|
|
||
| The cardinality of `error.type` within one instrumentation library SHOULD be low. | ||
| Telemetry consumers that aggregate data from multiple instrumentation libraries and applications | ||
| should be prepared for `error.type` to have high cardinality at query time when no | ||
| additional filters are applied. | ||
|
|
||
| If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. | ||
|
|
||
| If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), | ||
| it's RECOMMENDED to: | ||
|
|
||
| - Use a domain-specific attribute | ||
| - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. | ||
|
|
||
| --- | ||
|
|
||
| `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. | ||
|
|
||
| | Value | Description | Stability | | ||
| |---|---|---| | ||
| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | | ||
|
|
||
| <!-- markdownlint-restore --> | ||
| <!-- prettier-ignore-end --> | ||
| <!-- END AUTOGENERATED TEXT --> | ||
| <!-- endsemconv --> | ||
|
|
||
| ## Client (caller) spans | ||
|
|
||
| <!-- semconv span.cli.client --> | ||
| <!-- 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 | | ||
| |---|---|---|---|---|---| | ||
| | [`process.executable.name`](/docs/attributes-registry/process.md) | string | The name of the process executable. On Linux based systems, can be set to the `Name` in `proc/[pid]/status`. On Windows, can be set to the base name of `GetProcessImageFileNameW`. | `otelcol` | `Required` |  | | ||
| | [`process.exit.code`](/docs/attributes-registry/process.md) | int | The exit code of the process. | `127` | `Required` |  | | ||
| | [`process.pid`](/docs/attributes-registry/process.md) | int | Process identifier (PID). | `1234` | `Required` |  | | ||
| | [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if and only if process.exit.code is not 0 |  | | ||
| | [`process.command_args`](/docs/attributes-registry/process.md) | string[] | All the command arguments (including the command/executable itself) as received by the process. On Linux-based systems (and some other Unixoid systems supporting procfs), can be set according to the list of null-delimited strings extracted from `proc/[pid]/cmdline`. For libc-based executables, this would be the full argv vector passed to `main`. | `["cmd/otecol", "--config=config.yaml"]` | `Recommended` |  | | ||
| | [`process.executable.path`](/docs/attributes-registry/process.md) | string | The full path to the process executable. On Linux based systems, can be set to the target of `proc/[pid]/exe`. On Windows, can be set to the result of `GetProcessImageFileNameW`. | `/usr/bin/cmd/otelcol` | `Recommended` |  | | ||
|
|
||
| **[1] `error.type`:** The `error.type` SHOULD be predictable, and SHOULD have low cardinality. | ||
|
|
||
| When `error.type` is set to a type (e.g., an exception type), its | ||
| canonical class name identifying the type within the artifact SHOULD be used. | ||
|
|
||
| Instrumentations SHOULD document the list of errors they report. | ||
|
|
||
| The cardinality of `error.type` within one instrumentation library SHOULD be low. | ||
| Telemetry consumers that aggregate data from multiple instrumentation libraries and applications | ||
| should be prepared for `error.type` to have high cardinality at query time when no | ||
| additional filters are applied. | ||
|
|
||
| If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`. | ||
|
|
||
| If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), | ||
| it's RECOMMENDED to: | ||
|
|
||
| - Use a domain-specific attribute | ||
| - Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not. | ||
|
|
||
| --- | ||
|
|
||
| `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. | ||
|
|
||
| | Value | Description | Stability | | ||
| |---|---|---| | ||
| | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | | ||
|
|
||
| <!-- markdownlint-restore --> | ||
| <!-- prettier-ignore-end --> | ||
| <!-- END AUTOGENERATED TEXT --> | ||
| <!-- endsemconv --> | ||
|
|
||
| [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| groups: | ||
| - id: span.cli.internal | ||
| type: span | ||
| span_kind: internal | ||
| stability: experimental | ||
| brief: > | ||
| Describes span of CLI (Command Line Interfaces) programs. | ||
| attributes: | ||
| - ref: process.executable.name | ||
| requirement_level: required | ||
| - ref: process.executable.path | ||
| requirement_level: recommended | ||
| - ref: process.pid | ||
| requirement_level: required | ||
| - ref: process.exit.code | ||
| requirement_level: required | ||
| - ref: process.command_args | ||
| requirement_level: recommended | ||
| - ref: error.type | ||
| requirement_level: | ||
| conditionally_required: if and only if process.exit.code is not 0 | ||
|
|
||
| - id: span.cli.client | ||
| type: span | ||
| span_kind: client | ||
| stability: experimental | ||
| brief: > | ||
| Describes span to calls of CLI (Command Line Interfaces) programs. | ||
| attributes: | ||
| - ref: process.executable.name | ||
| requirement_level: required | ||
| - ref: process.executable.path | ||
| requirement_level: recommended | ||
| - ref: process.pid | ||
| requirement_level: required | ||
| - ref: process.exit.code | ||
| requirement_level: required | ||
| - ref: process.command_args | ||
| requirement_level: recommended | ||
| - ref: error.type | ||
| requirement_level: | ||
| conditionally_required: if and only if process.exit.code is not 0 |