如何快速实现分布式追踪：Jaeger Client Node.js 完全指南

滑隽蔚Maia

418人浏览 · 2026-01-24 04:36:50

滑隽蔚Maia · 2026-01-24 04:36:50 发布

如何快速实现分布式追踪：Jaeger Client Node.js 完全指南

【免费下载链接】jaeger-client-node 🛑 This library is DEPRECATED! 项目地址: https://gitcode.com/gh_mirrors/ja/jaeger-client-node

Jaeger Client Node.js 是 Jaeger 分布式追踪系统的客户端库，它实现了 JavaScript OpenTracing API 1.0 规范，专为 Node.js 后端服务器设计。通过该库，开发者可以轻松为应用程序添加分布式追踪能力，监控和排查分布式系统中的性能问题。

什么是分布式追踪？

分布式追踪是一种用于监控和诊断分布式系统的技术，它通过记录请求在系统中的传播路径，帮助开发者理解系统行为、定位性能瓶颈。在微服务架构中，一个请求可能会经过多个服务，分布式追踪可以将这些服务间的调用关系可视化，形成完整的调用链。

Jaeger Client Node.js 的核心功能

1. 与 OpenTracing API 兼容

Jaeger Client Node.js 实现了 OpenTracing API 1.0 规范，这意味着开发者可以使用统一的 API 进行分布式追踪，而不必关心底层的实现细节。通过 initTracer 函数可以初始化一个符合 OpenTracing 规范的 Tracer 实例：

var initTracer = require('jaeger-client').initTracer;
var tracer = initTracer(config, options);

2. 多种采样策略

Jaeger Client Node.js 支持多种采样策略，以控制追踪数据的采集量，避免对系统性能造成过大影响。常见的采样器包括：

ConstSampler：始终采样或始终不采样
ProbabilisticSampler：按概率采样
RateLimitingSampler：按速率限制采样
RemoteSampler：从 Jaeger Agent 动态获取采样策略

可以通过环境变量 JAEGER_SAMPLER_TYPE 和 JAEGER_SAMPLER_PARAM 来配置采样器。

3. 灵活的报告机制

Jaeger Client Node.js 提供了多种报告器（Reporter），用于将追踪数据发送到 Jaeger 后端：

RemoteReporter：通过 UDP 或 HTTP 将数据发送到 Jaeger Agent 或 Collector
InMemoryReporter：将数据存储在内存中，适用于测试
LoggingReporter：将数据打印到日志
CompositeReporter：组合多个报告器

默认情况下，Tracer 通过 UDP 将 spans 发送到本地运行的 jaeger-agent，jaeger-agent 负责将 spans 转发给 jaeger-collector。如果需要直接通过 HTTP 发送 spans，可以配置 collectorEndpoint：

var tracer = initTracer({
  serviceName: 'my-service',
  reporter: {
    collectorEndpoint: 'http://jaeger-collector:14268/api/traces'
  }
}, options);

快速开始

安装

使用 npm 安装 Jaeger Client Node.js：

npm install --save jaeger-client

初始化 Tracer

以下是一个简单的初始化 Tracer 的示例：

var initTracer = require('jaeger-client').initTracer;

// 配置
var config = {
  serviceName: 'my-service',
  sampler: {
    type: 'const',
    param: 1, // 1 表示始终采样，0 表示不采样
  },
  reporter: {
    logSpans: true,
  },
};

// 选项
var options = {
  logger: {
    info: function logInfo(msg) {
      console.log('INFO ', msg);
    },
    error: function logError(msg) {
      console.log('ERROR', msg);
    },
  },
};

// 初始化 Tracer
var tracer = initTracer(config, options);

创建和使用 Span

Span 是分布式追踪的基本单位，表示一个独立的工作单元。以下是创建和使用 Span 的示例：

// 创建一个根 Span
var span = tracer.startSpan('op-name');

// 设置标签
span.setTag('key', 'value');

// 添加日志
span.log({ event: 'event-name', message: 'log message' });

// 创建子 Span
var childSpan = tracer.startSpan('child-op', { childOf: span.context() });

// 完成 Span
childSpan.finish();
span.finish();

注入和提取 Span 上下文

在分布式系统中，需要将 Span 上下文从一个服务传递到另一个服务，以便形成完整的调用链。Jaeger Client Node.js 提供了 inject 和 extract 方法来实现这一功能：

// 注入 Span 上下文到 HTTP 头
var httpCarrier = {};
tracer.inject(span.context(), opentracing.FORMAT_HTTP_HEADERS, httpCarrier);

// 在接收方提取 Span 上下文
var parentSpanContext = tracer.extract(opentracing.FORMAT_HTTP_HEADERS, httpCarrier);
var serverSpan = tracer.startSpan('server-op', { childOf: parentSpanContext });

环境变量配置

Jaeger Client Node.js 支持通过环境变量进行配置，方便在不同环境中进行部署：

环境变量	描述
JAEGER_SERVICE_NAME	服务名称
JAEGER_ENDPOINT	直接发送 spans 到 collector 的 HTTP 端点
JAEGER_REPORTER_LOG_SPANS	是否记录 spans 日志
JAEGER_REPORTER_FLUSH_INTERVAL	报告器刷新间隔（毫秒）
JAEGER_SAMPLER_TYPE	采样器类型
JAEGER_SAMPLER_PARAM	采样器参数
JAEGER_SAMPLER_MANAGER_HOST_PORT	远程采样器的 HTTP 端点

例如，可以通过以下环境变量配置采样器：

export JAEGER_SAMPLER_TYPE=probabilistic
export JAEGER_SAMPLER_PARAM=0.01

注意事项

UDP 大小限制：UDP 有 65,507 字节的硬大小限制，如果 span 超过此限制，tracer 会丢弃该 span。可以通过配置 HTTP 直接发送到 collector 来避免此问题。
应用退出时刷新：确保在应用退出时调用 tracer.close() 来刷新缓冲的 traces。
弃用通知：该库已被弃用，建议迁移到 OpenTelemetry。

总结

Jaeger Client Node.js 是一个功能强大的分布式追踪客户端库，它通过实现 OpenTracing API，为 Node.js 应用程序提供了便捷的分布式追踪能力。通过灵活的采样策略和报告机制，可以有效地监控和诊断分布式系统中的问题。虽然该库已被弃用，但对于仍在使用的项目，掌握其使用方法对于保障系统稳定性和性能至关重要。

如需了解更多详细信息，可以参考项目源码中的 src/configuration.js 文件，其中包含了完整的配置 schema。同时，也可以关注 OpenTelemetry 项目，以便及时进行迁移。

【免费下载链接】jaeger-client-node 🛑 This library is DEPRECATED! 项目地址: https://gitcode.com/gh_mirrors/ja/jaeger-client-node