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

ステータス: Development

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

HTTPクライアントリクエスト例外

Status:

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

このイベントは、HTTPクライアントリクエスト中に発生した例外（ネットワーク障害、タイムアウト、その他リクエストの正常な完了を妨げるエラーなど）を表します。

このイベントは、HTTPクライアント操作中に例外が発生した場合に記録すべきです（SHOULD）。計装は、このイベントを記録する際、重要度をWARN（重要度番号13）に設定すべきです（SHOULD）。一部のHTTPクライアントフレームワークは、成功しなかったHTTPステータスコード（例えば404 Not Found）について人為的な例外を生成します。可能な場合、計装はこれらの人為的な例外を記録するべきではなく（SHOULD NOT）、または重要度をDEBUG（重要度番号5）に設定すべきです（SHOULD）。計装は、対応するHTTPクライアントスパンで捉えられた属性を例外イベントに設定するための設定オプションを提供してもかまいません（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 が設定されていない場合は必須であり、それ以外の場合は推奨されます。

[2] exception.message:

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

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

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

HTTPサーバーリクエスト例外

Status:

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

このイベントは、HTTPサーバーリクエストの処理中に発生した例外（アプリケーションエラー、内部障害、その他サーバーによるリクエストの正常な処理を妨げる例外など）を表します。

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