CLI（コマンドラインインターフェース）プログラムに関するセマンティック規約

ステータス: Development

この文書では、CLIプログラムを計装する際に、呼び出し元と呼び出し先の両方の立場から適用すべきセマンティック規約を定義します。この文書は、実行を終了する短命なプログラムを対象としており、デーモンや長時間動作するバックグラウンドタスクは対象としていません。

実行（呼び出し先）スパン

Status:

このスパンは、呼び出し先の視点から見たCLI（コマンドラインインターフェース）プログラムの実行を表します。

Span name は {process.executable.name} に設定すべきです（SHOULD）。実行されるコマンドについて追加のコンテキストを持つ計装は、異なる低カーディナリティのスパン名の形式を使用してもかまわず（MAY）、その場合はそれを文書化すべきです（SHOULD）。

Span status は、エラーの記録の文書に従うべきです（SHOULD）。エラーは、{process.exit.code} 属性が0でない場合として定義されます。

Span kind は INTERNAL であるべきです（SHOULD）。

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`process.executable.name`	`Required`	string	プロセス実行ファイルの名前。Linuxベースのシステムでは、これは `/proc/[pid]/exe` の対象のベース名に設定すべきです（SHOULD）。Windowsでは、これは `GetProcessImageFileNameW` のベース名に設定すべきです（SHOULD）。	`otelcol`
`process.exit.code`	`Required`	int	プロセスの終了コード。	`127`
`process.pid`	`Required`	int	プロセス識別子（PID）。	`1234`
`error.type`	`Conditionally Required` process.exit.codeが0でない場合に限る	string	操作が終了したエラーのクラスを記述します。[1]	`timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500`
`process.command_args`	`Recommended`	string[]	プロセスが受け取った、すべてのコマンド引数（コマンド・実行ファイル自体を含む）。Linuxベースのシステム（およびprocfsをサポートする一部の他のUnix系システム）では、`proc/[pid]/cmdline` から抽出されたnull区切りの文字列一覧に従って設定できます。libcベースの実行ファイルの場合、これは `main` に渡された完全なargvベクトルになります。機密データを除外するサニタイズが行われている場合を除き、デフォルトで収集するべきではありません（SHOULD NOT）。	`["cmd/otecol", "--config=config.yaml"]`
`process.executable.path`	`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`	計装がカスタム値を定義していない場合に使用されるフォールバックのエラー値。

クライアント（呼び出し元）スパン