OpenTelemetry JS 中 Fetch 自动埋点的异常处理机制解析

自动埋点与 Fetch 请求的异常捕获

在使用 OpenTelemetry JS 的自动埋点功能时，开发者经常会遇到一个疑问：为什么通过 fetch 发起的请求返回 4xx 或 5xx 状态码时，异常没有被自动记录到 span 中？这实际上与浏览器 Fetch API 的设计机制和 OpenTelemetry 的实现原理密切相关。

Fetch API 的异常处理特性

Fetch API 与常见的 HTTP 客户端库（如 axios）有一个重要区别：它不会将 HTTP 错误状态码（4xx/5xx）视为异常抛出。这是 Fetch API 的底层设计特性，它只会在网络层面出现问题时（如域名解析失败、连接中断等）抛出真正的异常。

OpenTelemetry 的 fetch 自动埋点实现严格遵循了 Fetch API 的这一行为规范。因此，当服务器返回 400、404 或 500 等错误状态码时，由于 Fetch API 本身没有抛出异常，OpenTelemetry 自然也不会在 span 中记录异常事件。

自动埋点的生命周期管理

OpenTelemetry 的自动埋点对 fetch 请求的 span 生命周期管理非常精确：

1. span 在请求发起时创建
2. 在收到响应头时结束（无论状态码如何）
3. 此时响应体可能还未完全接收

这种设计确保了 span 的持续时间准确反映了网络请求的实际耗时。但这也意味着当开发者代码处理响应体或捕获异常时，相关的 span 已经结束，无法再添加额外的事件或属性。

解决方案与实践建议

对于需要记录 HTTP 错误状态码的场景，开发者有以下几种解决方案：

1. 使用 applyCustomAttributesOnSpan 回调

可以在初始化 fetch 埋点时配置 applyCustomAttributesOnSpan 回调，基于响应对象添加自定义属性：

new FetchInstrumentation({
  applyCustomAttributesOnSpan: (span, request, response) => {
    if (response.status >= 400) {
      span.setAttribute('http.error', true);
      span.setAttribute('http.status_code', response.status);
    }
  }
});

需要注意的是，此回调执行时响应体可能还未完全接收，因此无法基于响应内容添加属性。

2. 创建业务逻辑层 Span

更完整的解决方案是在业务逻辑方法层面创建自定义 span：

import { trace, context } from '@opentelemetry/api';

async function getEmail(email) {
  const tracer = trace.getTracer('user-service');
  const span = tracer.startSpan('getEmail');
  
  return context.with(trace.setSpan(context.active(), span), async () => {
    try {
      const response = await fetch(`/api/email/${email}`);
      if (!response.ok) {
        throw new Error(`HTTP error: ${response.status}`);
      }
      return await response.json();
    } catch (err) {
      span.recordException(err);
      throw err;
    } finally {
      span.end();
    }
  });
}

这种方法可以捕获业务层面的异常和错误状态，提供更完整的可观测性数据。

最佳实践总结

1. 理解不同 HTTP 客户端库的异常处理差异
2. 根据业务需求选择合适的埋点层级
3. 对于关键业务逻辑，建议添加手动埋点
4. 合理利用 OpenTelemetry 提供的各种配置选项
5. 在微服务架构中保持一致的错误处理策略

通过正确理解 OpenTelemetry 的自动埋点机制和 Fetch API 的特性，开发者可以构建出更可靠、更易观测的前端应用。