来自浏览器的 OpenTelemetry 追踪

用于浏览器的 OpenTelemetry JavaScript SDK 由多个软件包组成：@opentelemetry/sdk-trace-web 提供核心追踪实现，@opentelemetry/instrumentation-fetch 会自动为所有 fetch API 调用创建跨度，@opentelemetry/exporter-trace-otlp-http 会将跨度发送到采集器。

TracerProvider 是 OpenTelemetry 中的核心配置对象。它保存 SpanProcessors 列表（用于决定已完成跨度的处理方式）、描述应用的资源信息（服务名称、版本），以及采样配置。

BatchSpanProcessor 会在内存中收集已完成的跨度，然后批量导出，而不是逐个发送跨度。这样可以大幅减少向采集器发送的 HTTP 请求数量，提升浏览器性能，并减轻 OTel 采集器端点的负载。

OTLPTraceExporter 会通过 HTTP，以 JSON 或 protobuf 格式将批量跨度发送到兼容 OpenTelemetry 的采集器。您只需配置采集器 URL（例如 OTel 采集器代理端点），导出器就会自动处理序列化和重试逻辑。

跨度表示追踪中的一个独立工作单元，例如组件挂载、API 调用或用户交互。跨度包含名称、开始时间、结束时间、状态（OK 或 ERROR）以及一组键值属性。相关跨度通过共享的追踪 ID 和父子关系关联起来。

您可以使用 provider.getTracer('react-app') 创建追踪器，并使用 tracer.startSpan('component-mount') 开始跨度。工作完成后，调用 span.end() 记录结束时间。请始终结束跨度——泄漏的跨度会浪费内存，并在您的可观测性后端中产生不完整的数据。

属性可以使用上下文数据丰富跨度：span.setAttribute('user.id', userId) 或 span.setAttribute('route', location.pathname)。属性可以在可观测性后端中搜索，从而支持这样的查询：“显示用户 42 的所有缓慢跨度”或“显示 /checkout 路由上的所有错误”。

@opentelemetry/instrumentation-fetch 会修改全局 fetch 函数，为每个发出的 HTTP 请求自动创建跨度。跨度会捕获 URL、方法、HTTP 状态码和持续时间，无需更改现有的 fetch 调用。

当 fetch 插桩为传出请求创建跨度时，它会将 W3C TraceContext 的 traceparent 标头注入请求中。接收方后端读取此标头并继续同一条追踪链，从而创建一条连接浏览器与服务器的追踪链。

OpenTelemetry 初始化必须在任何组件挂载之前完成——通常位于应用入口文件（main.tsx）中，在调用 ReactDOM.createRoot 之前。创建提供程序，注册处理器和导出器，并调用 provider.register()，使其成为全局 TracerProvider。

在高流量应用中记录每次用户交互会生成海量追踪数据。请在 TracerProvider 中配置 TraceIdRatioBased 采样器（例如对 10% 的追踪进行采样）以减少数据量。请始终使用 ParentBased 采样器对 100% 的错误追踪进行采样，确保不会遗漏任何错误。

为什么在浏览器应用中使用 BatchSpanProcessor，而不是 SimpleSpanProcessor？

OpenTelemetry JavaScript SDK 使用 TracerProvider、BatchSpanProcessor 和 OTLPTraceExporter 为浏览器添加插桩。跨度表示经过属性丰富的工作单元。Fetch 插桩会自动为 API 调用创建跨度，并注入 W3C TraceContext 标头，以实现端到端的分布式追踪。请尽早初始化，合理进行采样，并始终结束跨度，以保持整洁的追踪数据。