> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/cicd/cicd-spans/ # CI/CDスパンに関するセマンティック規約 **ステータス**: [Release Candidate][DocumentStatus] ## CI/CDスパン この節で説明する規約は、継続的インテグレーション/継続的デプロイ（CI/CD）システムに固有のものです。 適用可能な[CI/CDおよびVCSのリソース規約][cicdres]は、使用されるべきです（SHOULD）。 [cicdres]: /works/otel-specs-ja/semconv/resource/cicd/ "CI/CDおよびVCSのリソース規約" ### パイプライン実行 **Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) このスパンは、CI/CDパイプラインの実行を記述します。 すべてのパイプライン実行について、パイプライン実行の処理に対応する`SERVER`種別のスパンが作成されるべきです（SHOULD）。 **スパン名**は、[スパン名に関する全般的なガイドライン](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.59.0/specification/trace/api.md#span)に従わなければなりません（MUST）。 （カーディナリティの低い）パイプライン名が利用可能な場合、スパン名は`{action} {pipeline}`であるべきです（SHOULD）。パイプライン名が利用できないか、高いカーディナリティを持つ可能性が高い場合、スパン名は`{action}`であるべきです（SHOULD）。 `{action}`は、[`cicd.pipeline.action.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/#cicd-pipeline-action-name)であるべきです（SHOULD）。 `{pipeline}`は、[`cicd.pipeline.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/#cicd-pipeline-name)であるべきです（SHOULD）。 **スパン種別**は`SERVER`であるべきです（SHOULD）。 **スパンステータス**は[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)文書に従うべきです（SHOULD）。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`cicd.pipeline.result`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | パイプライン実行の結果。 | `success`; `failure`; `timeout`; `skip` | | [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if the pipeline result is `failure` or `error` | string | 操作が終了したエラーのクラスを記述します。[1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`cicd.pipeline.action.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `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` | パイプライン実行がビルドを実施しています。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `RUN` | パイプライン実行が実行中です。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `SYNC` | パイプライン実行が同期を実施しています。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | --- `cicd.pipeline.result`には、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `cancellation` | パイプライン実行がキャンセルされました。たとえばユーザーが手動でキャンセルした場合。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `error` | CI/CDシステムでのエラー（ワーカーが強制終了された場合など）により、パイプライン実行が失敗しました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `failure` | コンパイルエラーやテスト失敗などにより、パイプライン実行が正常に終了しませんでした。このような失敗は通常、パイプライン実行中に実行されたツールの非0の終了コードによって検出されます。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `skip` | 前提条件が満たされなかったなどの理由で、パイプライン実行がスキップされました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `success` | パイプライン実行が正常に終了しました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `timeout` | タイムアウトによってパイプライン実行が中断されました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | --- `error.type`には、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### パイプラインタスクの実行 **Status:** ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) このスパンは、パイプライン実行内でのタスクの実行を記述します。 **スパン種別**は`INTERNAL`であるべきです（SHOULD）。 **スパンステータス**は[エラーの記録](/works/otel-specs-ja/semconv/general/recording-errors/)文書に従うべきです（SHOULD）。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`cicd.pipeline.task.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | パイプライン内のタスクの人間が読める名前。ここでのタスクは、パイプラインにおける[計算処理](https://wikipedia.org/wiki/Pipeline_(computing))に最も近い概念です。タスクの別の呼び方には、コマンド、ステップ、手順などがあります。 | `Run GoLang Linter`; `Go Build`; `go-test`; `deploy_binary` | | [`cicd.pipeline.task.run.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | パイプライン内でのタスク実行の一意な識別子。[1] | `12097` | | [`cicd.pipeline.task.run.result`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | タスク実行の結果。 | `success`; `failure`; `timeout`; `skip` | | [`cicd.pipeline.task.run.url.full`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | パイプラインタスク実行を特定・位置付けるための完全なアドレスを提供する、パイプラインタスク実行の[URL](https://wikipedia.org/wiki/URL)。 | `https://github.com/open-telemetry/semantic-conventions/actions/runs/9753949763/job/26920038674?pr=1075` | | [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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）。 記録されたエラー型が、失敗の分類にとって意味を持たないラッパーである場合、計装は内側のエラーの型を代わりに使用してもかまいません（MAY）。たとえばGoでは、ラッパー型が失敗の分類に役立たない場合、`%w`を使って`fmt.Errorf`で作成されたエラーをアンラップしてもかまいません（MAY）。 計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。 1つの計装ライブラリ内における`error.type`のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルタが適用されない場合、クエリ実行時に`error.type`が高いカーディナリティを持つことを想定しておくべきです（should）。 操作が正常に完了した場合、計装は`error.type`を設定すべきではありません（SHOULD NOT）。 特定のドメインが独自のエラー識別子の集合（HTTPやRPCのステータスコードなど）を定義している場合、次のことが推奨されます（RECOMMENDED）。 - ドメイン固有の属性を使用する。 - そのドメイン固有の集合に定義されているかどうかにかかわらず、すべてのエラーを捕捉するように`error.type`を設定する。 サンプリングの判断において重要となりうる次の属性は、**スパン作成時点**で（提供する場合は）提供されるべきです（SHOULD）。 * [`cicd.pipeline.task.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) * [`cicd.pipeline.task.run.id`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) * [`cicd.pipeline.task.run.url.full`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/cicd/) --- `cicd.pipeline.task.run.result`には、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `cancellation` | タスク実行がキャンセルされました。たとえばユーザーが手動でキャンセルした場合。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `error` | CI/CDシステムでのエラー（ワーカーが強制終了された場合など）により、タスク実行が失敗しました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `failure` | コンパイルエラーやテスト失敗などにより、タスク実行が正常に終了しませんでした。このような失敗は通常、タスク実行中に実行されたツールの非0の終了コードによって検出されます。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `skip` | 前提条件が満たされなかったなどの理由で、タスク実行がスキップされました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `success` | タスク実行が正常に終了しました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | | `timeout` | タイムアウトによってタスク実行が中断されました。 | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | --- `error.type`には、次のよく知られた値の一覧があります。これらのいずれかが該当する場合は、対応する値を使用しなければなりません（MUST）。そうでない場合は、独自の値を使用してもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装が独自の値を定義していない場合に使用するフォールバック用のエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status