> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/exceptions/exceptions-logs/ # ログにおける例外に関するセマンティック規約 **ステータス**: [Stable, except where otherwise specified][DocumentStatus] この文書は、[Logger API](/works/otel-specs-ja/spec/logs/api/#logger)を通じて発行される[ログ](/works/otel-specs-ja/spec/logs/api/#logrecordの発行)上の例外を記録するためのセマンティック規約を定義します。 > [!IMPORTANT] > > 例外をスパンイベントとして記録している既存の計装は、次に従うべきです。 > > * 次の値をサポートする環境変数 `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` を導入すべきです（SHOULD）。 > * `logs` - 例外をログのみとして発行します。 > * `logs/dup` - スパンイベントとログの両方を発行し、段階的な移行を可能にします。 > * これらの値がいずれも指定されていない場合のデフォルトの動作は、例外をスパンイベントとして発行し続けることです（既存の動作）。 > * 両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持すべきです（SHOULD）。 > * 次のメジャーバージョンでは、この環境変数を削除し、例外をログのみとして発行してもかまいません（MAY）。 > > 計装が例外をログのみとして発行するようになった後も、ユーザーはSDK層でそれらをスパンイベントにルーティングするオプションを持ち続けます。 ## 例外の記録 > [!NOTE] > この文書は、例外イベントをどのように記録すべきか、またいつ記録を避けるべきかを説明します。例外をいつ記録すべきかについてのガイダンスは、個々のセマンティック規約の作成者に委ねられています。 OpenTelemetryセマンティック規約の作成者は、この文書に従って例外イベントを定義すべきです（SHOULD）。 このガイダンスは、OpenTelemetryにホストされていないアプリケーション開発者や計装にも推奨されます。 この文書は、ロギングブリッジには適用されません。 例外は、[Logger](/works/otel-specs-ja/spec/logs/api/#logger)のemit操作に渡される[LogRecord](/works/otel-specs-ja/spec/logs/data-model/#log-and-event-record-definition)上の属性として記録すべきです（SHOULD）。 同じ操作についてスパンも記録する計装によって発行される例外イベントは、対応するスパンコンテキストと関連付けられなければなりません（MUST）。 言語実装が[Emit a LogRecord](/works/otel-specs-ja/spec/logs/api/#logrecordの発行) APIへの例外インスタンスの受け渡しをサポートしている場合、計装は個々の例外属性を手動で設定するのではなく、例外インスタンスを提供すべきです（SHOULD）。 ![Development](https://img.shields.io/badge/-development-blue) 計装は例外をイベントとして記録すべきです（SHOULD）。 ### 例外を記録すべきでない場合 **ステータス**: [Development][DocumentStatus] 一部のライブラリ、フレームワーク、ランタイムは、失敗を示すエラーコードで終わる操作に対して人為的な例外を生成します。可能な場合、計装はこれらの人為的な例外を記録すべきではありません（SHOULD NOT）。 例えば、Pythonの FastAPI は、失敗を示すステータスコードを持つレスポンスを返す代わりに、[`HTTPException`](https://fastapi.tiangolo.com/tutorial/handling-errors/#use-httpexception)をスローすることを推奨しています。同様に、JavaのSpringは[`ResponseStatusException`](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/server/ResponseStatusException.html)を提供しています。 ### イベント名 **ステータス**: [Development][DocumentStatus] `.exception` サフィックスを付けて、計装対象の操作を記述する[イベント名](/works/otel-specs-ja/semconv/general/events/)を提供することが推奨されます（RECOMMENDED）。 例えば、[`http.client.request.exception`](/works/otel-specs-ja/semconv/http/http-exceptions/#httpクライアントリクエスト例外)は、HTTPクライアントリクエスト中に発生する例外を表します。 特定の操作やドメインに固有ではない計装（例えばグローバルな未処理例外ハンドラーなど）は、`exception` イベント名を使うべきです（SHOULD）。 ### 重大度 **ステータス**: [Development][DocumentStatus] 重大度は、例外の存在そのものだけでなく、その想定される影響を反映します。 [重大度番号](/works/otel-specs-ja/spec/logs/data-model/#field-severitynumber)は、すべての例外イベントに提供すべきであり（SHOULD）、以下のガイダンスに従って、例外が発生する文脈に基づいて設定すべきです（SHOULD）。 #### FATAL重大度 通常アプリケーションのシャットダウンにつながる例外は、重大度 `FATAL`（重大度番号21）で記録すべきです（SHOULD）。 例: - アプリケーションが起動時に無効な設定を検出し、シャットダウンする。 - アプリケーションがメモリ不足の状態に陥る。 > [!NOTE] > 計装はこのようなエラーを記録するために最大限努力すべきですが（SHOULD）、OpenTelemetryのSDKやエクスポーターが実際にそれらをエクスポートする機会を持てない場合があります。 #### ERROR重大度 アプリケーションコードによって処理されず、アプリケーションのシャットダウンにつながらない例外は、重大度 `ERROR`（重大度番号17）で記録すべきです（SHOULD）。 `SERVER` または `CONSUMER` スパンを定義するセマンティック規約は、対応する例外イベントも定義し、`ERROR` 重大度の使用を推奨すべきです（SHOULD）。 例: - メッセージングのコンシューマーが、例外によってメッセージ処理を終了する。 - HTTPサーバーフレームワークのエラーハンドラーが、アプリケーションコードによって処理されなかった例外を捕捉する。 #### WARN重大度 アプリケーションコードによって処理されることが期待される例外は、重大度 `WARN`（重大度番号13）で報告すべきです（SHOULD）。 `CLIENT` または `PRODUCER` スパンを定義するセマンティック規約は、対応する例外イベントも定義し、`WARN` 重大度の使用を推奨すべきです（SHOULD）。 例: - リモートサービスへの接続試行がタイムアウトする。 - ファイルへのデータの書き込みがI/O例外を引き起こす。 - 基盤となるサービスが利用不可のため、リトライを使い果たした後にクライアントライブラリの呼び出しが失敗する。クライアントライブラリの計装は単一のWARNログを記録し、個々のリトライ試行のログ記録は、より低レベルの計装に委ねられる。 #### INFO重大度 アプリケーション開発者は、例外を記録するために `INFO` 重大度（番号9）を使ってもかまいません（MAY）。 #### DEBUG重大度 実際の問題を示さない例外は、重大度 `DEBUG`（重大度番号5）で記録すべきです（SHOULD）。 例えば、クライアント側でリクエストがキャンセルされたことを示す例外が、サーバー上でスローされ、サーバーの計装によって検出される場合です。 #### TRACE重大度 アプリケーション開発者は、例外を記録するために `TRACE` 重大度（番号1）を使ってもかまいません（MAY）。セマンティック規約の作成者は、`TRACE` 重大度で例外イベントを定義すべきではありません（SHOULD NOT）。 ### 属性 以下の表は、[LogRecord](/works/otel-specs-ja/spec/logs/data-model/#log-and-event-record-definition)に追加すべき属性を示しています。 ![Development](https://img.shields.io/badge/-development-blue) 計装は、例外が発生した文脈を記述する追加の属性を提供してもかまいません（MAY）。同じ操作についてスパンも記録する計装は、対応するスパン上で捕捉された属性で例外イベントを設定する設定オプションを提供してもかまいません（MAY）。 **Attributes:** | Key | Stability | [Requirement Level](/works/otel-specs-ja/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`exception.message`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/exception/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [1] | string | 例外メッセージ。 [2] | `Division by zero`; `Can't convert 'int' object to str implicitly` | | [`exception.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/exception/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` [3] | string | 例外の型（該当する場合はその完全修飾クラス名）。この言語がサポートしている場合、静的な型よりも例外の動的な型を優先すべきです。 [4] | `java.net.ConnectException`; `OSError` | | [`exception.stacktrace`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/exception/) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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）。 ### スタックトレースの表現 [トレースのセマンティック規約における例外 - スタックトレースの表現](/works/otel-specs-ja/semconv/exceptions/exceptions-spans/#スタックトレースの表現)と同じです。 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status