3、异常事件定义：什么是 Span 异常事件、Exception 语义约定、异常事件的属性结构

在 OpenTelemetry 体系中，异常事件（Exception Event）是 Span 上承载错误信息的关键载体。它并非直接修改 Span 状态，而是通过事件机制将异常细节附加到 Span 上，从而保留完整的错误上下文。本章将深入解析异常事件的定义、语义约定及其属性结构，为后续的路由策略打下基础。

3.1 什么是 Span 异常事件

Span 异常事件是 OpenTelemetry 规范中预定义的一种特殊事件类型，用于记录应用程序中发生的异常。与简单的日志不同，异常事件具有标准化的属性结构，能够被 Collector 和后端系统统一解析和处理。

异常事件与 Span 状态的关系如下表所示：

3.2 Exception 语义约定

OpenTelemetry 为异常事件定义了严格的语义约定（Semantic Conventions），确保不同语言 SDK 生成的异常事件具有一致的属性名称和含义。这些约定是 Collector 进行异常路由和聚合的基础。

异常事件的事件名称固定为 exception，其核心属性包括：

以下是一个符合语义约定的异常事件示例（以 JSON 格式表示）：

{
  "name": "exception",
  "timeUnixNano": "1698765432123456789",
  "attributes": [
    {
      "key": "exception.type",
      "value": { "stringValue": "java.lang.NullPointerException" }
    },
    {
      "key": "exception.message",
      "value": { "stringValue": "Cannot invoke method on null object" }
    },
    {
      "key": "exception.stacktrace",
      "value": { "stringValue": "java.lang.NullPointerException\n\tat com.example.service.UserService.getUser(UserService.java:42)\n\tat ..." }
    },
    {
      "key": "exception.escaped",
      "value": { "boolValue": true }
    }
  ]
}

3.3 异常事件的属性结构

异常事件的属性结构遵循 OpenTelemetry 的通用属性模型，每个属性由 键（Key）和 值（Value）组成。值可以是字符串、布尔、整数、浮点数、数组或键值列表等类型。

在 Collector 内部，异常事件被表示为 plog.LogRecord 的一部分，其属性结构可以通过以下 SVG 图直观理解：

3.4 异常事件与 Span 的关联方式

异常事件通过 Span 的事件列表（Events）与 Span 关联。每个事件包含时间戳、名称和属性集合。Collector 在处理时，可以通过以下方式识别和提取异常事件：

• 按事件名称过滤：筛选 name == "exception" 的事件
• 按属性键值路由：根据 exception.type 或 exception.message 的值进行分发
• 按时间范围聚合：利用事件的时间戳进行时序分析

下表总结了异常事件在不同场景下的典型属性组合：