可观测性与稳定性 / 系统课时

记录属性、事件、状态与异常

记录属性、事件、状态与异常

只看到 Span 名称和耗时,通常还不足以解释一次请求为什么失败。本课把属性、事件、状态与异常放进同一个 Span:既能按业务维度筛选,又能还原关键瞬间,并明确区分“发生异常”与“操作失败”。

学习目标

  • 区分 Span 属性、事件、状态与异常各自承担的诊断职责。
  • 使用 OpenTelemetry JavaScript API 为一次业务操作补齐可定位问题的证据。
  • 避免高基数、敏感数据和错误状态记录等常见埋点问题。

四种证据回答不同问题

属性适合描述 Span 整段生命周期都成立、并且值得筛选或聚合的维度;事件表示某个时间点发生了什么;状态给出这次操作整体是否失败;异常则保存错误类型、消息和堆栈等故障细节。是否真正建立索引由后端决定,因此“可检索”不等于可以无限写入任意字段。

信息 适合回答的问题 JavaScript API
属性 哪个订单、租户、重试次数或业务类型出现问题 setAttribute() / setAttributes()
事件 在 Span 生命周期中的哪个关键瞬间发生了什么 addEvent()
状态 这次操作整体是否失败 setStatus()
异常 失败时抛出了什么错误以及堆栈是什么 recordException()

成功路径通常保持默认的 UNSET 即可;只有确实需要显式声明成功时才设置 OK。recordException() 会记录异常证据,但不会替你表达“这次操作整体失败”,因此错误路径通常还要设置 ERROR 状态。

在一个失败 Span 上留下完整证据

下面用 Node.js 手工创建一个结算 Span。先在空目录安装所需依赖:

bash
npm init -y
npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

预期输出:

text
added <COUNT> packages, and audited <COUNT> packages in <TIME>

实际包数量和耗时会随 npm 缓存及依赖版本变化。然后把下面的完整示例保存为 span-evidence.mjs:

js
import { SpanStatusCode, trace } from '@opentelemetry/api';
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-base';

const provider = new NodeTracerProvider({
  spanProcessors: [
    new SimpleSpanProcessor(new ConsoleSpanExporter()),
  ],
});
provider.register();

const tracer = trace.getTracer('checkout-demo');

tracer.startActiveSpan('checkout.confirm', (span) => {
  span.setAttributes({
    'app.order.id': 'order-1001',
    'app.payment.provider': 'demo-pay',
    'app.retry.count': 0,
  });

  span.addEvent('payment.authorize.start', {
    'app.payment.amount': 199,
  });

  try {
    // 故意制造失败,观察异常事件与 Span 状态如何同时保留。
    throw new Error('card declined');
  } catch (error) {
    if (error instanceof Error) {
      span.recordException(error);
      span.addEvent('payment.authorize.failed', {
        'app.failure.type': 'declined',
      });
    }

    span.setStatus({
      code: SpanStatusCode.ERROR,
      message: 'payment authorization failed',
    });
  } finally {
    span.end();
  }
});

await provider.shutdown();

运行:

bash
node span-evidence.mjs

预期结果:

text
name: checkout.confirm
attributes: app.order.id=order-1001, app.payment.provider=demo-pay, app.retry.count=0
events: payment.authorize.start, exception, payment.authorize.failed
status: ERROR
status.message: payment authorization failed
traceId/spanId/timestamp: <ID>/<ID>/<TIME>

ConsoleSpanExporter 的具体对象格式和字段顺序可能随 SDK 版本不同,但应能确认以上关键信息。其中 exception 是 recordException() 产生的异常事件,而两个业务事件由 addEvent() 明确记录。

记录时守住数据边界

属性应优先选择稳定、有限且确实有查询价值的维度。不要把完整请求体、令牌、银行卡号、邮箱等敏感信息写入 Span;对订单号这类高基数标识,也要先确认后端成本和保留策略,而不是把所有业务字段都当成标签。

事件适合“支付开始”“库存预留失败”这类瞬时证据;如果某段工作本身有独立持续时间、需要单独看耗时或产生子调用,应考虑创建子 Span,而不是只塞一个事件。所有属性、事件、状态和异常都应在 span.end() 之前写入。

排障时可以把四类信息串起来看:先用属性缩小问题范围,再按事件恢复时间线,查看状态判断操作结果,最后用异常定位具体失败原因。这样一个 Span 才从“耗时记录”变成真正可用于定位问题的业务证据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

记录属性、事件、状态与异常

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通