9.7 KiB

Raw Blame History

Semantic conventions for CLI (command line interface) programs

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.

Execution (callee) spans

Status:

This span describes CLI (Command Line Interfaces) program execution from a callee perspective.

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. Refer to the Recording Errors document for details on how to record span status.

Span kind SHOULD be INTERNAL.

Attribute	Type	Description	Examples	Requirement Level
`process.executable.name`	string	The name of the process executable. On Linux based systems, this SHOULD be set to the base name of the target of `/proc/[pid]/exe`. On Windows, this SHOULD be set to the base name of `GetProcessImageFileNameW`.	`otelcol`	`Required`
`process.exit.code`	int	The exit code of the process.	`127`	`Required`
`process.pid`	int	Process identifier (PID).	`1234`	`Required`
`error.type`	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`	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`. SHOULD NOT be collected by default unless there is sanitization that excludes sensitive data.	`["cmd/otecol", "--config=config.yaml"]`	`Recommended`
`process.executable.path`	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.

Client (caller) spans