来自前端的金融科技 OpenTelemetry 追踪

金融科技端到端追踪：从前端到 OpenTelemetry Collector

在分布式金融科技系统中，缺乏 traceId 的日志无法将 500 错误回溯至用户的具体操作。OpenTelemetry 通过 OpenTelemetry Collector 实现端到端追踪——覆盖单页应用（SPA）前端、后端服务全链路。我们基于 TypeScript 的实现采用 CompositeLogger 并对 fetch 进行增强，确保资金转账等核心业务流程的 Span 层级关系完整准确。

前端开发者须掌握的 OpenTelemetry 核心概念

OpenTelemetry 统一了可观测性数据采集标准：追踪（traces）、Span、事件（events）与属性（attributes）。

• Trace（追踪） —— 根结构，由唯一 traceId 标识，用于聚合关联的 Span。
• Span（跨度） —— 具有时序的原子操作，含起止时间戳；支持嵌套，真实反映调用层级。
• Event（事件） —— 关联至某 Span 的带时间戳行为，可附加自定义属性。
• Attribute（属性） —— 键值对形式的元数据，支撑过滤、检索与上下文增强。

借助这些基础构件，您可完整追踪一次用户点击，直至下游后端集成环节。

可观测性架构概览

前端通过审计微服务（Audit Microservice）将追踪数据发送至 OpenTelemetry Collector；后端服务（含产品与平台团队）则将遥测数据分别路由至 Jaeger（追踪）、Prometheus（指标）和 Kibana（日志）。Grafana 提供统一可视化看板。

该架构的核心优势：

• 集中式接入：前端无需直连内部可观测性基础设施，安全可控。
• 渐进式落地：按微服务分批灰度上线，显著降低实施风险。
• 敏感数据脱敏为强制要求：非可选项，而是合规底线。

前端实现：日志器接口设计

基础抽象是跨平台一致的日志器 Logger 接口：

export interface Logger {
  readonly name: string;
  init?(options?: CompositeInitOptions | SentryInitOptions | AuditInitOptions): void;
  logError(error: Error, context?: ErrorContextType | ErrorContextType[]): void;
  logMessage?(message: string, context?: Record<string, unknown>): void;
}

CompositeLogger 采用组合模式，将日志事件分发至多个底层日志器（OpenTelemetry、Sentry、Audit）：

export class CompositeLogger implements Logger {
  public readonly name = "composite";

  constructor(private readonly loggers: Logger[]) {}

  init(options?: CompositeInitOptions): void {
    this.loggers.forEach((logger) => {
      logger.init?.(options?.[logger.name as keyof CompositeInitOptions]);
    });
  }

  logError(error: Error, context?: ErrorContextType[]): void {
    this.loggers.forEach((logger) => {
      logger.logError(error, context);
    });
  }

  logMessage(message: string, context?: Record<string, unknown>): void {
    this.loggers.forEach((logger) => {
      logger.logMessage?.(message, context);
    });
  }

  startBusinessProcess(name: string, attributes?: Attributes): void {
    this.loggers.forEach((logger) => {
      if (logger.name === "otlp") {
        (logger as OtlpLogger).startBusinessProcess(name, attributes);
      }
    });
  }

  addEvent(name: string, attributes?: Attributes): void {
    this.loggers.forEach((logger) => {
      if (logger.name === "otlp") {
        (logger as OtlpLogger).addEvent(name, attributes);
      }
    });
  }
}

React 集成：基于 Context 的日志器注入

LoggerProvider 与 useLogger 钩子让日志器能力无缝贯穿整个组件树：

import React, { createContext, useContext } from "react";
import { CompositeLogger } from "./composite-logger";

const LoggerContext = createContext<CompositeLogger | null>(null);

export const LoggerProvider: React.FC<{
  logger: CompositeLogger;
  children: React.ReactNode;
}> = ({ logger, children }) => (
  <LoggerContext.Provider value={logger}>{children}</LoggerContext.Provider>
);

export const useLogger = (): CompositeLogger => {
  const logger = useContext(LoggerContext);
  if (!logger) {
    throw new Error("上下文未提供 Logger 实例");
  }
  return logger;
};

OtlpLogger：增强 fetch + StackContextManager 上下文管理

OtlpLogger 初始化 WebTracerProvider，自动增强 fetch 方法以透传父 Span 上下文，并利用 StackContextManager 解决浏览器异步场景下的上下文丢失问题——确保子 Span 能精准挂载至业务流程，全程无需手动传递上下文。

示例：资金转账全流程

• startBusinessProcess('money-transfer')
• addEvent('form-step-1', {amount: 1000})
• 发起 fetch 请求至后端——自动继承当前 Span 上下文
• 集成失败时调用 logError，完整保留全链路追踪血缘

实施收益

• 平均故障修复时间（MTTR）降低 10 倍以上：依托 traceId 在前后端日志中一键过滤，定位效率跃升。
• 高扩展性：新增日志器（如 Datadog、Honeycomb）仅需 npm 安装，零应用代码修改。
• 结构化关联：统一属性规范，实现前后端事件的毫秒级精准匹配。

Jaeger 可视化清晰呈现完整链路：用户点击 → API 请求 → Kafka 消息队列 → 平台后端服务。

关键结论

• 端到端追踪 以 traceId 为唯一真相源，彻底打通前后端日志孤岛。
• CompositeLogger 封装复杂性，同时支持多目标遥测输出，开发者专注业务逻辑。
• 增强版 fetch 确保 Span 层级严格准确，即使跨异步网络调用亦无失真。
• StackContextManager 消除现代 JavaScript 框架中客户端追踪的模板代码负担。
• 敏感数据脱敏 是金融科技领域监管合规的刚性要求，不可妥协。

— Editorial Team