> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/cli/cli-spans/ # CLI（コマンドラインインターフェース）プログラムに関するセマンティック規約 **ステータス**: [Development][DocumentStatus] この文書では、CLIプログラムを計装する際に、呼び出し元と呼び出し先の両方の立場から適用すべきセマンティック規約を定義します。この文書は、実行を終了する短命なプログラムを対象としており、デーモンや長時間動作するバックグラウンドタスクは対象としていません。 ## 実行（呼び出し先）スパン **Status:** ![Development](https://img.shields.io/badge/-development-blue) このスパンは、呼び出し先の視点から見たCLI（コマンドラインインターフェース）プログラムの実行を表します。 **Span name** は `{process.executable.name}` に設定すべきです（SHOULD）。 実行されるコマンドについて追加のコンテキストを持つ計装は、異なる低カーディナリティのスパン名の形式を使用してもかまわず（MAY）、その場合はそれを文書化すべきです（SHOULD）。 **Span status** は、[エラーの記録](https://opentelemetry.io/docs/specs/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。 エラーは、`{process.exit.code}` 属性が0でない場合として定義されます。 **Span kind** は `INTERNAL` であるべきです（SHOULD）。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`process.executable.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | プロセス実行ファイルの名前。Linuxベースのシステムでは、これは `/proc/[pid]/exe` の対象のベース名に設定すべきです（SHOULD）。Windowsでは、これは `GetProcessImageFileNameW` のベース名に設定すべきです（SHOULD）。 | `otelcol` | | [`process.exit.code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | int | プロセスの終了コード。 | `127` | | [`process.pid`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | int | プロセス識別子（PID）。 | `1234` | | [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` process.exit.codeが0でない場合に限る | string | 操作が終了したエラーのクラスを記述します。[1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`process.command_args`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string[] | プロセスが受け取った、すべてのコマンド引数（コマンド・実行ファイル自体を含む）。Linuxベースのシステム（およびprocfsをサポートする一部の他のUnix系システム）では、`proc/[pid]/cmdline` から抽出されたnull区切りの文字列一覧に従って設定できます。libcベースの実行ファイルの場合、これは `main` に渡された完全なargvベクトルになります。機密データを除外するサニタイズが行われている場合を除き、デフォルトで収集するべきではありません（SHOULD NOT）。 | `["cmd/otecol", "--config=config.yaml"]` | | [`process.executable.path`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | プロセス実行ファイルへの完全なパス。Linuxベースのシステムでは、`proc/[pid]/exe` の対象に設定できます。Windowsでは、`GetProcessImageFileNameW` の結果に設定できます。 | `/usr/bin/cmd/otelcol` | **[1] `error.type`:** `error.type` は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。 `error.type` が型（例えば例外の型）に設定される場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。 記録されたエラー型が、失敗の分類にとって意味のないラッパーである場合、計装は代わりに内部のエラーの型を使用してもかまいません（MAY）。例えば、Goでは、`%w` を使って `fmt.Errorf` で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、ラップが解除されてもかまいません（MAY）。 計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。 1つの計装ライブラリ内での `error.type` のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には `error.type` が高カーディナリティになることを想定しておくべきです。 操作が正常に完了した場合、計装は `error.type` を設定するべきではありません（SHOULD NOT）。 特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。 - ドメイン固有の属性を使用する - そのドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように `error.type` を設定する --- `error.type` には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。 | Value | Description | Stability | | --- | --- | --- | | `_OTHER` | 計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## クライアント（呼び出し元）スパン **Status:** ![Development](https://img.shields.io/badge/-development-blue) このスパンは、呼び出し元の視点から見たCLI（コマンドラインインターフェース）プログラムの実行を表します。 **Span name** は `{process.executable.name}` に設定すべきです（SHOULD）。 実行されるコマンドについて追加のコンテキストを持つ計装は、異なる低カーディナリティのスパン名の形式を使用してもかまわず（MAY）、その場合はそれを文書化すべきです（SHOULD）。 **Span status** は、[エラーの記録](https://opentelemetry.io/docs/specs/semconv/general/recording-errors/)の文書に従うべきです（SHOULD）。 エラーは、`{process.exit.code}` 属性が0でない場合として定義されます。 **Span kind** は `CLIENT` であるべきです（SHOULD）。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`process.executable.name`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | string | プロセス実行ファイルの名前。Linuxベースのシステムでは、これは `/proc/[pid]/exe` の対象のベース名に設定すべきです（SHOULD）。Windowsでは、これは `GetProcessImageFileNameW` のベース名に設定すべきです（SHOULD）。 | `otelcol` | | [`process.exit.code`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | int | プロセスの終了コード。 | `127` | | [`process.pid`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Required` | int | プロセス識別子（PID）。 | `1234` | | [`error.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/error/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` process.exit.codeが0でない場合に限る | string | 操作が終了したエラーのクラスを記述します。[1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`process.command_args`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string[] | プロセスが受け取った、すべてのコマンド引数（コマンド・実行ファイル自体を含む）。Linuxベースのシステム（およびprocfsをサポートする一部の他のUnix系システム）では、`proc/[pid]/cmdline` から抽出されたnull区切りの文字列一覧に従って設定できます。libcベースの実行ファイルの場合、これは `main` に渡された完全なargvベクトルになります。機密データを除外するサニタイズが行われている場合を除き、デフォルトで収集するべきではありません（SHOULD NOT）。 | `["cmd/otecol", "--config=config.yaml"]` | | [`process.executable.path`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/process/) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Recommended` | string | プロセス実行ファイルへの完全なパス。Linuxベースのシステムでは、`proc/[pid]/exe` の対象に設定できます。Windowsでは、`GetProcessImageFileNameW` の結果に設定できます。 | `/usr/bin/cmd/otelcol` | **[1] `error.type`:** `error.type` は予測可能であるべきであり（SHOULD）、低カーディナリティであるべきです（SHOULD）。 `error.type` が型（例えば例外の型）に設定される場合、そのアーティファクト内で型を識別する正規のクラス名を使用すべきです（SHOULD）。 記録されたエラー型が、失敗の分類にとって意味のないラッパーである場合、計装は代わりに内部のエラーの型を使用してもかまいません（MAY）。例えば、Goでは、`%w` を使って `fmt.Errorf` で作成されたエラーは、ラッパー型が失敗の分類に役立たない場合、ラップが解除されてもかまいません（MAY）。 計装は、報告するエラーの一覧を文書化すべきです（SHOULD）。 1つの計装ライブラリ内での `error.type` のカーディナリティは低くあるべきです（SHOULD）。複数の計装ライブラリやアプリケーションからのデータを集約するテレメトリーの利用者は、追加のフィルターが適用されないクエリ時には `error.type` が高カーディナリティになることを想定しておくべきです。 操作が正常に完了した場合、計装は `error.type` を設定するべきではありません（SHOULD NOT）。 特定のドメインが独自のエラー識別子の集合を定義している場合（HTTPやRPCのステータスコードなど）、次のことが推奨されます（RECOMMENDED）。 - ドメイン固有の属性を使用する - そのドメイン固有の集合内で定義されているかどうかにかかわらず、すべてのエラーを捉えるように `error.type` を設定する --- `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