> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/exceptions/exceptions-spans/


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

**ステータス**: [Deprecated][DocumentStatus]<br>
代わりに[ログにおける例外に関するセマンティック規約](/works/otel-specs-ja/semconv/exceptions/exceptions-logs/)を使ってください。

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

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

## 例外イベント

<!-- semconv event.exception -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

**Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen)

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

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

**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.escaped`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/exception/) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>スパンのスコープをエスケープしない、処理済みの例外の記録は、もはや推奨されません。 | `Recommended` | boolean | その例外がスパンのスコープをエスケープしていることを示します。 | |
| [`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）。

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

### スタックトレースの表現

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

| Language   | Format                                                             |
| ---------- | ------------------------------------------------------------------ |
| C#         | the return value of [Exception.ToString()][csharp-stacktrace]      |
| Elixir     | the return value of [Exception.format/3][elixir-stacktrace]        |
| Erlang     | the return value of [`erl_error:format`][erlang-stacktrace]        |
| Go         | the return value of [runtime.Stack][go-stacktrace]                 |
| Java       | the contents of [Throwable.printStackTrace()][java-stacktrace]     |
| JavaScript | the return value of [error.stack][js-stacktrace] as returned by V8 |
| Python     | the return value of [traceback.format_exc()][python-stacktrace]    |
| Ruby       | the return value of [Exception.full_message][ruby-full-message]    |

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

[gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report
[java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29
[python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc
[js-stacktrace]: https://v8.dev/docs/stack-trace-api
[ruby-full-message]: https://docs.ruby-lang.org/en/3.4/Exception.html#method-i-full_message
[csharp-stacktrace]: https://docs.microsoft.com/dotnet/api/system.exception.tostring
[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack
[telemetry-sdk-resource]: https://opentelemetry.io/docs/specs/semconv/resource/#telemetry-sdk
[erlang-stacktrace]: https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3
[elixir-stacktrace]: https://hexdocs.pm/elixir/1.14.3/Exception.html#format/3
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status