CLI（命令行界面）程序的语义约定

本文档定义了在对 CLI 程序进行插桩时应应用的语义约定，包括作为调用者和被调用者。本文档适用于执行结束的短时程序，即不适用于守护进程或长时间运行的后台任务。

执行（被调用者）span

状态:

此 span 从被调用者的角度描述 CLI（命令行界面）程序的执行。

Span name 应设置为 {process.executable.name}。拥有已执行命令额外上下文的插桩可以（MAY）使用不同的低基数 span 名称格式，并应（SHOULD）将其文档化。

Span status 应遵循 Recording Errors 文档。当 {process.exit.code} 属性不为 0 时，定义为 Error。

Span 类型应为 INTERNAL。

Attributes

键	需求级别	Value Type	描述	Example Values
`process.executable.name`	`必需`	字符串	进程可执行文件的名称。在基于 Linux 的系统上，应将其设置为 `/proc/[pid]/exe` 目标的基名称。在 Windows 上，应将其设置为 `GetProcessImageFileNameW` 的基名称。	`otelcol`
`process.exit.code`	`必需`	int	进程的退出代码。	`127`
`process.pid`	`必需`	int	进程标识符 (PID)。	`1234`
`error.type`	仅当 process.exit.code 不为 0 时，才“有条件地必需”。	字符串	描述操作最终结束的一类错误。[1]	`timeout`；`java.net.UnknownHostException`；`server_certificate_invalid`；`500`
`process.command_args`	`推荐`	string[]	进程接收到的所有命令行参数（包括命令/可执行文件本身）。在基于 Linux 的系统（以及其他支持 procfs 的类 Unix 系统）上，可以根据从 `proc/[pid]/cmdline` 提取的空分隔字符串列表进行设置。对于基于 libc 的可执行文件，这将是传递给 `main` 的完整 argv 向量。除非进行了排除敏感数据的清理，否则默认不应收集。	`["cmd/otecol", "--config=config.yaml"]`
`process.executable.path`	`推荐`	字符串	进程可执行文件的完整路径。在基于 Linux 的系统上，可以设置为 `proc/[pid]/exe` 的目标。在 Windows 上，可以设置为 `GetProcessImageFileNameW` 的结果。	`/usr/bin/cmd/otelcol`

[1] error.type： error.type 应该可预测，并且应该具有低基数性。

当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。

Instrumentations 应该记录它们报告的错误列表。

一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。

如果操作已成功完成，Instrumentations 不应设置 error.type。

如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
`_OTHER`	当检测不到自定义值时使用的回退错误值。

状态:

此 span 从调用者的角度描述 CLI（命令行界面）程序的执行。

Span name 应设置为 {process.executable.name}。拥有已执行命令额外上下文的插桩可以（MAY）使用不同的低基数 span 名称格式，并应（SHOULD）将其文档化。

Span status 应遵循 Recording Errors 文档。当 {process.exit.code} 属性不为 0 时，定义为 Error。

**Span 类型**应为 CLIENT。