CICD Span 的语义约定

状态: 开发中

CICD Span

本节所述的约定特定于持续集成/持续部署 (CICD) 系统。

应使用所有适用的 CICD 和 VCS 资源约定。

Pipeline run

状态: 开发中

此 Span 描述了一个 CICD pipeline run。

对于所有 pipeline run，都应创建一个 SERVER 类型的 Span 来对应 pipeline run 的执行。

Span name 必须遵循整体的 span name 指导原则。

如果存在（低基数）的 pipeline name，则 span name 应为 {action} {pipeline}。如果 pipeline name 不可用或可能具有高基数，则 span name 应为 {action}。

{action} 应为 cicd.pipeline.action.name。

{pipeline} 应为 cicd.pipeline.name。

Span kind 应为 SERVER。

**Span 状态**应遵循 记录错误文档。

Attributes

键Stability需求级别Value Type描述Example Values
cicd.pipeline.resultDevelopment必需字符串流水线运行的结果。success; failure; timeout; skipped
error.typeStable如果 pipeline 结果为 failure 或 error，则 Conditionally Required。字符串描述操作最终结束的一类错误。[1]timeout；java.net.UnknownHostException；server_certificate_invalid；500
cicd.pipeline.action.nameDevelopment选择加入字符串pipeline run 正在执行的操作类型。BUILD; RUN; SYNC

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

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

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

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

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

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

  • 使用特定于域的属性
  • 设置 error.type 以捕获所有错误，无论它们是否包含在特定于域的集合中。

cicd.pipeline.action.name 具有以下预定义值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值描述Stability
BUILDpipeline run 正在执行构建。Development
RUNpipeline run 正在执行。Development
SYNCpipeline run 正在执行同步。Development

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

值描述Stability
cancellation流水线运行被取消，例如，由用户手动取消流水线运行。Development
错误流水线运行因 CICD 系统中的错误而失败，例如，由于工作者被终止。Development
failure流水线运行未成功完成，例如，由于编译错误或测试失败。此类失败通常由流水线运行中执行的工具的非零退出码检测到。Development
skip流水线运行被跳过，例如，由于未满足先决条件。Development
success流水线运行已成功完成。Development
timeout超时导致流水线运行被中断。Development

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

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

Pipeline task run

状态: 开发中

此 Span 描述了 pipeline run 中的任务执行。

Span 类型应为 INTERNAL。

**Span 状态**应遵循 记录错误文档。

Attributes

键Stability需求级别Value Type描述Example Values
cicd.pipeline.task.nameDevelopment必需字符串pipeline 中任务的可读名称。这里的任务最接近 计算过程。任务的其他术语包括命令、步骤和过程。Run GoLang Linter; Go Build; go-test; deploy_binary
cicd.pipeline.task.run.idDevelopment必需字符串pipeline 中任务 run 的唯一标识符。12097
cicd.pipeline.task.run.resultDevelopment必需字符串任务 run 的结果。success; failure; timeout; skipped
cicd.pipeline.task.run.url.fullDevelopment必需字符串pipeline 任务 run 的 URL，提供定位和识别 pipeline 任务 run 的完整地址。https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075
error.typeStable如果任务结果为 failure 或 error，则 Conditionally Required。字符串描述操作最终结束的一类错误。[1]timeout；java.net.UnknownHostException；server_certificate_invalid；500

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

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

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

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

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

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

  • 使用特定于域的属性
  • 设置 error.type 以捕获所有错误，无论它们是否包含在特定于域的集合中。

以下属性对于做出采样决策可能很重要，并且应在跨度创建时提供（如果提供的话）

cicd.pipeline.task.run.result 具有以下预定义值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值描述Stability
cancellation任务 run 被取消，例如，用户手动取消任务 run。Development
错误任务 run 因 CICD 系统中的错误而失败，例如，由于 worker 被终止。Development
failure任务 run 未成功完成，例如，由于编译错误或测试失败。此类失败通常由任务 run 中执行的工具的非零退出代码检测到。Development
skip任务 run 被跳过，例如，由于未满足先决条件。Development
success任务 run 已成功完成。Development
timeout超时导致任务 run 被中断。Development

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

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