💥 OpenTelemetry 异常处理，不知道这个会出大问题！(兼顾性能与稳定性的秘诀)

8 月 25, 2026

—

cslab

in IT Security

“系统明明发生了故障…为什么我的仪表盘上却显示一切正常？” 🧐

这是每个开发者都可能经历过的惊险时刻。辛辛苦苦搭建的 Observability 系统，在最关键的时刻却保持沉默。原因可能就是 OpenTelemetry 的异常处理没有“正确”进行。

今天，我们将探讨 OpenTelemetry 异常处理的“黄金法则”，它能帮助您兼顾性能和问题解决的实用性。

🎯 核心：完美异常处理的3个黄金法则

直奔主题。OpenTelemetry 异常处理的精髓就是这3个组合：

span.record_exception(): 记录异常的详细信息（如堆栈跟踪）。
span.set_status(ERROR): 明确将当前 Span 的状态标记为“失败”。
raise (Re-throw): 重新抛出异常，不干扰应用程序的原始流程。

只有将这三者结合使用，才能实现完美的异常追踪。让我们逐一详细了解。

📜 步骤1：留下详细线索 – record_exception()

当异常发生时，首先要做的是详细记录“发生了什么”。 span.record_exception(e) 正是承担这一职责。

作用: 在 Span 中添加一个名为“exception”的特殊事件(Event)。这个事件中包含了以下宝贵信息：
异常类型: ZeroDivisionError, NullPointerException 等
异常消息: 错误发生的原因
堆栈跟踪(Stack Trace): 导致错误发生的完整函数调用路径 🗺️
为什么这样做更好？ (性能 🚀): 如果将所有这些信息都存储在 Span 的属性(Attribute)中会怎样？像堆栈跟踪这样大容量的文本会给后端系统（例如 Elasticsearch）的索引带来巨大负担。 record_exception 将其作为“事件”处理，从而避免了搜索和聚合性能的下降。

🚨 步骤2：“我出问题了！”明确告知 – set_status(ERROR)

记录了异常信息后，现在需要告知所有人这个 Span 已经“失败”了。

span.set_status(Status(StatusCode.ERROR, “错误摘要消息”)) 正是扮演这个扩音器的角色。

作用: 将该 Span 在视觉上设置为“失败”状态。在 Grafana 或 Jaeger 等可观测性 UI 中会以红色显示，即使在数千个追踪中也能一目了然地发现问题。
如果不使用它会怎样？: 仅使用 record_exception 会留下异常记录，但在追踪列表中可能仍显示为“成功”。这就像生病了却不说出来一样。最终，您会错过问题排查的黄金时间。

🌪️ 步骤3：我的职责已完成，回到原始流程 – 重新抛出异常 (raise)

这是最重要也最常犯的错误。记录异常后，必须重新抛出它。

作用: 将 catch 块中处理的异常再次传递给上层调用者。
为什么必须这样做？: OpenTelemetry 是应用程序的“观察者”，而不是“操纵者”。如果捕获(catch)并吞掉(swallow)异常，应用程序会认为没有错误发生。
可怕的后果 😨:
数据库事务可能不会回滚，反而被提交。
API 服务器可能向用户发送 200 OK 响应而不是 500 错误。
全局异常处理逻辑可能不工作，导致后续处理缺失。

OpenTelemetry 不应阻碍应用程序正常的错误处理流程。

🖥️ 全局视图：通过代码理解

现在，让我们通过 Python 代码来了解这三个原则是如何协同工作的。

from opentelemetry import trace
from opentelemetry.trace.status import Status, StatusCode

tracer = trace.get_tracer(__name__)

def process_data(data):
    # 在当前 Span 上下文中启动新的 Span
    with tracer.start_as_current_span("process_data") as span:
        try:
            # 🕵️‍♂️ 提前添加对调试有用的上下文信息（属性）是个好习惯。
            span.set_attribute("data.size", len(data))

            # 💣 执行可能引发异常的危险操作
            result = 100 / len(data) # 如果 len(data) 为 0，则会发生 ZeroDivisionError
            span.set_attribute("result", result)

            # 成功时默认值为 OK，因此可以省略。
            # span.set_status(Status(StatusCode.OK))
            return result

        except Exception as e:
            # ❗ 应用三步黄金法则 ❗

            # 1️⃣ 步骤：将 Span 状态设置为 ERROR
            error_message = f"Failed to process data: {e}"
            span.set_status(Status(StatusCode.ERROR, error_message))

            # 2️⃣ 步骤：将详细异常信息（包括堆栈跟踪）记录为事件
            span.record_exception(e)

            # 3️⃣ 步骤：重新抛出异常，以进行正常的应用程序错误处理
            raise

# 函数使用示例
try:
    # 故意引发错误的情况
    process_data("")
except ZeroDivisionError:
    # 由于 'raise'，即使在应用程序的顶层也能识别和处理异常。
    print("Application handled the ZeroDivisionError correctly. ✅")

❌ 为什么这些方法行不通？ (反模式)

仅使用 record_exception: 堆栈跟踪会被记录，但 UI 中仍显示成功（绿色），容易错过问题。 😴
仅使用 set_status(ERROR): 可以知道 Span 失败了，但由于没有堆栈跟踪，很难找到“为什么”失败的根本原因。 ❓
不 raise 异常 (最糟糕！): 追踪可能看起来正常，但实际上会导致应用程序数据一致性被破坏或向用户发送错误响应等严重 bug。 💣

✨ 总结：完美异常处理的清单

最后，在 OpenTelemetry 中处理异常时，请记住这张表格。


项目	推荐策略	为什么这样做？ (原因)
📜 记录异常	span.record_exception(e)	性能+调试: 将堆栈跟踪作为事件记录，减少后端负载，并提供所有必要的根因分析信息。
🚨 状态标记	span.set_status(Status(StatusCode.ERROR, …))	可见性: 在 UI 中即时识别失败的追踪，加快问题解决速度。
🌪️ 流程控制	重新抛出异常 (raise)	稳定性: 确保应用程序固有的错误处理逻辑（回滚、错误响应等）正常运行。
🕵️‍♂️ 上下文	在错误发生前通过 span.set_attribute() 添加相关信息	调试: 通过了解错误发生时的 user_id, request_id 等周边情况，为调试提供决定性线索。