CI/CDスパンに関するセマンティック規約

ステータス: Release Candidate

CI/CDスパン

この節で説明する規約は、継続的インテグレーション/継続的デプロイ（CI/CD）システムに固有のものです。

適用可能なCI/CDおよびVCSのリソース規約は、使用されるべきです（SHOULD）。

パイプライン実行

Status:

このスパンは、CI/CDパイプラインの実行を記述します。

すべてのパイプライン実行について、パイプライン実行の処理に対応するSERVER種別のスパンが作成されるべきです（SHOULD）。

スパン名は、スパン名に関する全般的なガイドラインに従わなければなりません（MUST）。

（カーディナリティの低い）パイプライン名が利用可能な場合、スパン名は{action} {pipeline}であるべきです（SHOULD）。パイプライン名が利用できないか、高いカーディナリティを持つ可能性が高い場合、スパン名は{action}であるべきです（SHOULD）。

{action}は、cicd.pipeline.action.nameであるべきです（SHOULD）。

{pipeline}は、cicd.pipeline.nameであるべきです（SHOULD）。

スパン種別はSERVERであるべきです（SHOULD）。

スパンステータスはエラーの記録文書に従うべきです（SHOULD）。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`cicd.pipeline.result`	`Required`	string	パイプライン実行の結果。	`success`; `failure`; `timeout`; `skip`
`error.type`	`Conditionally Required` if the pipeline result is `failure` or `error`	string	操作が終了したエラーのクラスを記述します。[1]	`timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500`
`cicd.pipeline.action.name`	`Opt-In`	string	パイプライン実行が実施しているアクションの種類。	`BUILD`; `RUN`; `SYNC`

[1] error.type: error.typeは予測可能であるべきであり（SHOULD）、カーディナリティが低いべきです（SHOULD）。

error.typeに型（たとえば例外の型）を設定する場合、そのアーティファクト内でその型を識別する正規のクラス名を使用すべきです（SHOULD）。

記録されたエラー型が、失敗の分類にとって意味を持たないラッパーである場合、計装は内側のエラーの型を代わりに使用してもかまいません（MAY）。たとえばGoでは、ラッパー型が失敗の分類に役立たない場合、%wを使ってfmt.Errorfで作成されたエラーをアンラップしてもかまいません（MAY）。

計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。

1つの計装ライブラリ内におけるerror.typeのカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルタが適用されない場合、クエリ実行時にerror.typeが高いカーディナリティを持つことを想定しておくべきです（should）。

操作が正常に完了した場合、計装はerror.typeを設定すべきではありません（SHOULD NOT）。

特定のドメインが独自のエラー識別子の集合（HTTPやRPCのステータスコードなど）を定義している場合、次のことが推奨されます（RECOMMENDED）。

ドメイン固有の属性を使用する。
そのドメイン固有の集合に定義されているかどうかにかかわらず、すべてのエラーを捕捉するようにerror.typeを設定する。

cicd.pipeline.action.nameには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

Value	Description	Stability
`BUILD`	パイプライン実行がビルドを実施しています。
`RUN`	パイプライン実行が実行中です。
`SYNC`	パイプライン実行が同期を実施しています。

cicd.pipeline.resultには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

Value	Description	Stability
`cancellation`	パイプライン実行がキャンセルされました。たとえばユーザーが手動でキャンセルした場合。
`error`	CI/CDシステムでのエラー（ワーカーが強制終了された場合など）により、パイプライン実行が失敗しました。
`failure`	コンパイルエラーやテスト失敗などにより、パイプライン実行が正常に終了しませんでした。このような失敗は通常、パイプライン実行中に実行されたツールの非0の終了コードによって検出されます。
`skip`	前提条件が満たされなかったなどの理由で、パイプライン実行がスキップされました。
`success`	パイプライン実行が正常に終了しました。
`timeout`	タイムアウトによってパイプライン実行が中断されました。

error.typeには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

Value	Description	Stability
`_OTHER`	計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。

パイプラインタスクの実行

Status:

このスパンは、パイプライン実行内でのタスクの実行を記述します。

スパン種別はINTERNALであるべきです（SHOULD）。

スパンステータスはエラーの記録文書に従うべきです（SHOULD）。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`cicd.pipeline.task.name`	`Required`	string	パイプライン内のタスクの人間が読める名前。ここでのタスクは、パイプラインにおける計算処理に最も近い概念です。タスクの別の呼び方には、コマンド、ステップ、手順などがあります。	`Run GoLang Linter`; `Go Build`; `go-test`; `deploy_binary`
`cicd.pipeline.task.run.id`	`Required`	string	パイプライン内でのタスク実行の一意な識別子。[1]	`12097`
`cicd.pipeline.task.run.result`	`Required`	string	タスク実行の結果。	`success`; `failure`; `timeout`; `skip`
`cicd.pipeline.task.run.url.full`	`Required`	string	パイプラインタスク実行を特定・位置付けるための完全なアドレスを提供する、パイプラインタスク実行のURL。	`https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075`
`error.type`	`Conditionally Required` if the task result is `failure` or `error`	string	操作が終了したエラーのクラスを記述します。[2]	`timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500`

[1] cicd.pipeline.task.run.id: 与えられたパイプライン実行とタスクについて、cicd.pipeline.task.run.idはその実行の中で一意でなければなりません（MUST）。同じパイプラインの異なる実行にわたる同じタスクについては、cicd.pipeline.task.run.idは同じ値のままでもかまいません（MAY）。これにより、複数のパイプライン実行にわたってcicd.pipeline.task.run.resultの値を関連付けられるようになります。

[2] error.type: error.typeは予測可能であるべきであり（SHOULD）、カーディナリティが低いべきです（SHOULD）。

error.typeに型（たとえば例外の型）を設定する場合、そのアーティファクト内でその型を識別する正規のクラス名を使用すべきです（SHOULD）。

計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。

操作が正常に完了した場合、計装はerror.typeを設定すべきではありません（SHOULD NOT）。

特定のドメインが独自のエラー識別子の集合（HTTPやRPCのステータスコードなど）を定義している場合、次のことが推奨されます（RECOMMENDED）。

ドメイン固有の属性を使用する。
そのドメイン固有の集合に定義されているかどうかにかかわらず、すべてのエラーを捕捉するようにerror.typeを設定する。

サンプリングの判断において重要となりうる次の属性は、スパン作成時点で（提供する場合は）提供されるべきです（SHOULD）。

cicd.pipeline.task.run.resultには、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。

Value	Description	Stability
`cancellation`	タスク実行がキャンセルされました。たとえばユーザーが手動でキャンセルした場合。
`error`	CI/CDシステムでのエラー（ワーカーが強制終了された場合など）により、タスク実行が失敗しました。
`failure`	コンパイルエラーやテスト失敗などにより、タスク実行が正常に終了しませんでした。このような失敗は通常、タスク実行中に実行されたツールの非0の終了コードによって検出されます。
`skip`	前提条件が満たされなかったなどの理由で、タスク実行がスキップされました。
`success`	タスク実行が正常に終了しました。
`timeout`	タイムアウトによってタスク実行が中断されました。

Value	Description	Stability
`_OTHER`	計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。