Semantic conventions for CLI (command line interface) programs

Status: Development

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 follow the Recording Errors document. An Error is defined as when the {process.exit.code} attribute is not 0.

Span kind SHOULD be INTERNAL.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
process.executable.name		Required	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
process.exit.code		Required	int	The exit code of the process.	127
process.pid		Required	int	Process identifier (PID).	1234
error.type		Conditionally Required if and only if process.exit.code is not 0	string	Describes a class of error the operation ended with. [1]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
process.command_args		Recommended	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"]
process.executable.path		Recommended	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

[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

Status:

This span describes CLI (Command Line Interfaces) program execution from a caller 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 follow the Recording Errors document. An Error is defined as when the {process.exit.code} attribute is not 0.

Span kind SHOULD be CLIENT.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
process.executable.name		Required	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
process.exit.code		Required	int	The exit code of the process.	127
process.pid		Required	int	Process identifier (PID).	1234
error.type		Conditionally Required if and only if process.exit.code is not 0	string	Describes a class of error the operation ended with. [1]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
process.command_args		Recommended	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"]
process.executable.path		Recommended	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

[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.