RPC例外に関するセマンティック規約

ステータス: Development

この文書では、RPC操作における例外の記録に関するセマンティック規約を定義します。

RPCクライアント呼び出し例外

Status:

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

このイベントは、送信中のRPC呼び出しで発生した例外を表します。例えば、ネットワーク障害、タイムアウト、シリアライズエラー、その他呼び出しの正常な完了を妨げるエラーなどです。

このイベントは、RPCクライアント呼び出し操作中に例外が発生した場合に記録されるべきです（SHOULD）。計装は、このイベントを記録する際に重大度をWARN（重大度番号13）に設定すべきです（SHOULD）。計装は、対応するRPCクライアントスパンに記録された属性を例外イベントに反映させる設定オプションを提供してもかまいません（MAY）。

Attributes:

Key	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.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 が設定されていない場合は必須（Required）で、それ以外の場合は推奨（Recommended）です。

[2] exception.message:

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

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

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

RPCサーバー呼び出し例外

Status:

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

このイベントは、受信中のRPC呼び出し処理で発生した例外を表します。例えば、アプリケーションエラー、内部障害、その他サーバーが呼び出しを正常に処理することを妨げる例外などです。

このイベントは、RPCサーバー呼び出し処理中に例外が発生した場合に記録されるべきです（SHOULD）。計装は、このイベントを記録する際に重大度をERROR（重大度番号17）に設定すべきです（SHOULD）。計装は、対応するRPCサーバースパンに記録された属性を例外イベントに反映させる設定オプションを提供してもかまいません（MAY）。