日志中的异常语义约定

状态: 稳定

本文档定义了通过 日志 API 发出的 日志 中记录异常的语义约定。

记录异常

异常 SHOULD 作为属性记录在传递给 LogRecord 的 Logger 发送操作中。异常 MAY 根据上下文记录在“日志”或“事件”中。

为了封装异常的正确处理，API 作者 MAY 提供一个构造函数、RecordException 方法/扩展，或类似的辅助机制，在 LogRecord 类/结构上，或者在任何最适合的地方，具体取决于语言运行时。

Attributes

下表显示了应添加到 LogRecord 的属性及其类型。

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.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，则为必需；否则，推荐设置。

堆栈跟踪表示

与 异常的追踪语义约定 - 堆栈跟踪表示 相同。