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

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

Attribute	Type	Description	Examples	Requirement Level	Stability
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.	["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.