OpenTelemetry-js 中自定义采样器的实现与问题排查

前言

在使用 OpenTelemetry 进行分布式追踪时，采样是一个重要的优化手段。本文将深入探讨如何在 OpenTelemetry-js 中实现自定义采样器，并解决实际开发中遇到的一个典型问题。

采样器基础概念

采样器决定了哪些追踪数据会被记录和导出。OpenTelemetry 提供了几种内置采样器：

1. AlwaysOnSampler：记录所有追踪数据
2. AlwaysOffSampler：不记录任何追踪数据
3. TraceIdRatioBasedSampler：基于追踪ID的比例采样

自定义采样器实现

在实际项目中，我们经常需要根据特定条件过滤掉不需要的追踪数据。例如，对于某些健康检查端点或特定的HTTP方法，我们可能不希望记录追踪信息。

实现思路

1. 继承 TraceIdRatioBasedSampler 基类
2. 重写 shouldSample 方法
3. 在方法中添加自定义过滤逻辑

关键代码分析

class CustomSampler extends TraceIdRatioBasedSampler {
  public readonly excludeHttpMethods = HTTP_METHOD_BLACKLIST;
  public readonly excludeHttpRoutes = HTTP_ROUTE_BLACKLIST;

  shouldSample(
    context: Context,
    traceId: string,
    _spanName: string,
    _spanKind: SpanKind,
    attributes: Attributes,
    _links: Array<Link>
  ): SamplingResult {
    // 先执行父类的采样逻辑
    const radioSampleDecision = super.shouldSample(context, traceId);
    
    // 如果父类决定不记录，直接返回
    if (radioSampleDecision.decision === SamplingDecision.NOT_RECORD) {
      return radioSampleDecision;
    }

    // 获取HTTP方法和路由属性
    const httpMethod = attributes['http.method'] ?? attributes[ATTR_HTTP_REQUEST_METHOD];
    const httpRoute = attributes['http.route'] ?? attributes[ATTR_HTTP_ROUTE];

    // 标准化属性值
    const normalizedHttpMethod = httpMethod?.toString().toUpperCase() ?? 'GET';
    const normalizedHttpRoute = httpRoute?.toString().toLowerCase() ?? '/';

    // 检查是否在黑名单中
    if (this.excludeHttpMethods.includes(normalizedHttpMethod) {
      return {
        ...radioSampleDecision,
        decision: SamplingDecision.NOT_RECORD,
      };
    }

    if (this.excludeHttpRoutes.includes(normalizedHttpRoute)) {
      return {
        ...radioSampleDecision,
        decision: SamplingDecision.NOT_RECORD,
      };
    }

    return radioSampleDecision;
  }
}

常见问题与解决方案

问题现象

虽然采样器返回了 NOT_RECORD 决策，但追踪数据仍然被发送到了收集器。

原因分析

1. 属性名称不一致：OpenTelemetry 中HTTP属性的命名可能有多个变体
2. 采样时机问题：采样器可能在Span创建后被调用
3. 配置问题：采样器可能没有正确注册到TracerProvider

解决方案

1. 统一属性名称检查：确保检查所有可能的属性名称变体
2. 验证采样器注册：确认采样器已正确配置
3. 调试输出：添加日志输出验证采样决策

最佳实践

1. 全面检查属性：考虑所有可能的属性名称变体
2. 单元测试：为采样器编写单元测试验证各种场景
3. 性能考虑：避免在采样器中执行复杂计算
4. 配置灵活性：考虑将过滤规则外部化，便于动态调整

总结

实现自定义采样器是OpenTelemetry使用中的重要技能。通过继承内置采样器并重写关键方法，我们可以灵活控制哪些追踪数据需要记录。遇到问题时，应从属性名称、配置正确性和执行时机等多个角度进行排查。