Span 上的异常语义约定
状态: 稳定
本文档定义了与 Span 关联的应用程序异常的记录语义约定。
异常事件
状态:
事件名称必须是 exception。
此事件描述单个异常。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
exception.message |  | 有条件地必需 [1] | 字符串 | 异常消息。 | Division by zero; Can't convert 'int' object to str implicitly |
exception.type | | 有条件地必需 [2] | 字符串 | 异常的类型（如果适用，则为完全限定类名）。在支持它的语言中，动态类型优先于静态类型。 | java.net.ConnectException; OSError |
exception.escaped |  不再建议记录已处理且未超出 Span 范围的异常。 | 推荐 | 布尔值 | 指示异常已超出 Span 的范围。 | |
exception.stacktrace | | 推荐 | 字符串 | 堆栈跟踪，作为自然语言运行时表示的字符串。表示方式由每个语言 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.type: 如果未设置 exception.message，则必需；否则，建议设置。
堆栈跟踪表示
下表改编自 Google Cloud，其中包含各种语言中堆栈跟踪的可能表示形式。此表并非对任何特定语言的建议，尽管 SIG 组织可以自行决定采用。
| 语言 | 格式 |
|---|---|
| C# | Exception.ToString() 的返回值 |
| Elixir | Exception.format/3 的返回值 |
| Erlang | erl_error:format 的返回值 |
| Go | runtime.Stack 的返回值 |
| Java | Throwable.printStackTrace() 的内容 |
| Javascript | V8 返回的 error.stack 的返回值 |
| Python | traceback.format_exc() 的返回值 |
| Ruby | Exception.full_message 的返回值 |
后端可以使用语言指定的堆栈跟踪生成方法，并结合来自 telemetry sdk resource 的平台信息，以在必要时提取更细粒度的堆栈跟踪信息。