スパンにおける例外に関するセマンティック規約

ステータス: Deprecated
代わりにログにおける例外に関するセマンティック規約を使ってください。

この文書は、スパンに関連付けられたアプリケーション例外を記録するためのセマンティック規約を定義します。

[!IMPORTANT]
例外をスパンイベントとして記録している既存の計装は、次に従うべきです。
次の値をサポートする環境変数 OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN を導入すべきです（SHOULD）。
logs - 例外をログのみとして発行します。
logs/dup - スパンイベントとログの両方を発行し、段階的な移行を可能にします。
これらの値がいずれも指定されていない場合のデフォルトの動作は、例外をスパンイベントとして発行し続けることです（既存の動作）。
両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持すべきです（SHOULD）。
次のメジャーバージョンでは、この環境変数を削除し、例外をログのみとして発行してもかまいません（MAY）。
計装が例外をログのみとして発行するようになった後も、ユーザーはSDK層でそれらをスパンイベントにルーティングするオプションを持ち続けます。

例外イベント

Status:

イベント名は exception でなければなりません（MUST）。

このイベントは単一の例外を記述します。

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
`exception.message`		`Conditionally Required` [1]	string	例外メッセージ。 [2]	`Division by zero`; `Can't convert 'int' object to str implicitly`
`exception.type`		`Conditionally Required` [3]	string	例外の型（該当する場合はその完全修飾クラス名）。この言語がサポートしている場合、静的な型よりも例外の動的な型を優先すべきです。 [4]	`java.net.ConnectException`; `OSError`
`exception.escaped`	スパンのスコープをエスケープしない、処理済みの例外の記録は、もはや推奨されません。	`Recommended`	boolean	その例外がスパンのスコープをエスケープしていることを示します。
`exception.stacktrace`		`Recommended`	string	言語ランタイムにおける自然な表現による文字列としてのスタックトレース。その表現は各言語のSIGによって決定・文書化されます。	`Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)`

[1] exception.message: exception.type が設定されていない場合は必須、それ以外の場合は推奨。

[2] exception.message:

[!WARNING]
この属性には機密情報が含まれる可能性があります。

[3] exception.type: exception.message が設定されていない場合は必須、それ以外の場合は推奨。

[4] exception.type: 記録される例外の型が、失敗の分類にとって意味を持たないラッパーである場合、計装は代わりに内部の例外の型を使ってもかまいません（MAY）。例えば、Goでは、%w を使って fmt.Errorf で作成されたエラーは、そのラッパー型が失敗の分類の助けにならない場合、アンラップしてもかまいません（MAY）。

スタックトレースの表現

Google Cloudから引用した以下の表は、さまざまな言語におけるスタックトレースの表現の候補を示しています。この表は特定の言語に対する推奨ではありませんが、SIGは適切と判断すれば自由に採用できます。

Language	Format
C#	the return value of Exception.ToString()
Elixir	the return value of Exception.format/3
Erlang	the return value of `erl_error:format`
Go	the return value of runtime.Stack
Java	the contents of Throwable.printStackTrace()
JavaScript	the return value of error.stack as returned by V8
Python	the return value of traceback.format_exc()
Ruby	the return value of Exception.full_message

バックエンドは、テレメトリーSDKリソースからのプラットフォーム情報と組み合わせて、言語ごとに指定された手法でスタックトレースを生成し、必要に応じてスタックトレースからより詳細な情報を抽出できます。