传播

上下文传播 JS SDK

The content of this page may be outdated and some links may be invalid. A newer version of this page exists in English.

More information ...

To see the changes to the English page since this page was last updated: visit GitHub compare 1aa53278..104c044c and search for content/en/docs/languages/js/propagation.md.

通过上下文传播，信号可以彼此关联，而不受其生成位置的限制。尽管上下文传播并不限于链路跟踪，但它允许链路在跨越进程和网络边界的任意分布式服务之间构建系统的因果关系信息。

在绝大多数用例中，原生支持 OpenTelemetry 的库或插桩库会自动为你在服务之间传播跟踪上下文。只有在极少数情况下，你才需要手动传播上下文。

要了解更多，请参阅上下文传播。

自动上下文传播

像插桩库这样的工具，如 @opentelemetry/instrumentation-http 或 @opentelemetry/instrumentation-express 会为你在服务之间传播上下文。

如果你遵循了入门指南，你可以创建一个客户端应用程序来查询 /rolldice 端点。

备注

你也可将本示例与其他任意语言快速入门指南中的示例应用整合使用。关联功能在不同编程语言编写的应用间均可生效，且无任何差异。

首先创建一个名为 dice-client 的新文件夹，然后安装所需的依赖项：

npm init -y
npm install undici \
  @opentelemetry/instrumentation-undici \
  @opentelemetry/sdk-node
npm install -D tsx  # 一个直接在 Node.js 中运行 TypeScript 文件的工具

npm init -y
npm install undici \
  @opentelemetry/instrumentation-undici \
  @opentelemetry/sdk-node

接下来，创建一个名为 client.ts（或 client.js）的新文件，内容如下：

/* client.ts */
import { NodeSDK } from '@opentelemetry/sdk-node';
import {
  SimpleSpanProcessor,
  ConsoleSpanExporter,
} from '@opentelemetry/sdk-trace-node';
import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';

const sdk = new NodeSDK({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
  instrumentations: [new UndiciInstrumentation()],
});
sdk.start();

import { request } from 'undici';

request('http://localhost:8080/rolldice').then((response) => {
  response.body.json().then((json: any) => console.log(json));
});

/* instrumentation.mjs */
import { NodeSDK } from '@opentelemetry/sdk-node';
import {
  SimpleSpanProcessor,
  ConsoleSpanExporter,
} from '@opentelemetry/sdk-trace-node';
import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';

const sdk = new NodeSDK({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
  instrumentations: [new UndiciInstrumentation()],
});
sdk.start();

const { request } = require('undici');

request('http://localhost:8080/rolldice').then((response) => {
  response.body.json().then((json) => console.log(json));
});

确保你在一个终端中运行了来自入门指南的插桩版本 app.ts（或 app.js）：

$ npx tsx --import ./instrumentation.ts app.ts
Listening for requests on http://localhost:8080

$ node --import ./instrumentation.mjs app.js
Listening for requests on http://localhost:8080

启动第二个终端并运行 client.ts（或 client.js）：

npx tsx client.ts

node client.js

两个终端都应该向控制台输出 Span 详细信息。客户端输出类似于以下内容：

{
  resource: {
    attributes: {
      // ...
    }
  },
  traceId: 'cccd19c3a2d10e589f01bfe2dc896dc2',
  parentSpanContext: undefined,
  traceState: undefined,
  name: 'GET',
  id: '6f64ce484217a7bf',
  kind: 2,
  timestamp: 1718875320295000,
  duration: 19836.833,
  attributes: {
    'url.full': 'http://localhost:8080/rolldice',
    // ...
  },
  status: { code: 0 },
  events: [],
  links: []
}

请注意 traceId（cccd19c3a2d10e589f01bfe2dc896dc2）和 ID（6f64ce484217a7bf）。这两个值也可以在客户端的输出中找到：

{
  resource: {
    attributes: {
      // ...
    }
  },
  traceId: 'cccd19c3a2d10e589f01bfe2dc896dc2',
  parentSpanContext: {
    traceId: 'cccd19c3a2d10e589f01bfe2dc896dc2',
    spanId: '6f64ce484217a7bf',
    traceFlags: 1,
    isRemote: true
  },
  traceState: undefined,
  name: 'GET /rolldice',
  id: '027c5c8b916d29da',
  kind: 1,
  timestamp: 1718875320310000,
  duration: 3894.792,
  attributes: {
    'http.url': 'http://localhost:8080/rolldice',
    // ...
  },
  status: { code: 0 },
  events: [],
  links: []
}

你的客户端和服务器应用程序成功报告了存在关联关系的 Span。如果你现在将两者都发送到后端，可视化将显示这种依赖关系。

手动上下文传播

在某些情况下，如上一节所述，不可能自动传播上下文。可能没有与你用于服务间通信的库相匹配的插桩库。或者即使存在，这些库也可能无法满足你的要求。

当你必须手动传播上下文时，你可以使用上下文 API。

通用示例

以下通用示例演示了如何手动传播链路上下文。

首先，在发送服务上，你需要注入当前的 context：

// 发送端服务
import { context, propagation, trace } from '@opentelemetry/api';

// 为承载链路信息的输出对象定义一个接口。
interface Carrier {
  traceparent?: string;
  tracestate?: string;
}

// 创建一个符合该接口规范的输出对象。
const output: Carrier = {};

// 将上下文中的 traceparent 和 tracestate 序列化至一个输出对象中。
//
// 本示例使用的是当前活跃的链路上下文，但你也可以根据自身业务场景，选用任何合适的上下文。
propagation.inject(context.active(), output);

// 从输出对象中提取 traceparent 和 tracestate 的值
const { traceparent, tracestate } = output;

// 随后你可将 traceparent 和 tracestate 数据传递至任何你所使用的、用于跨服务传播上下文的机制中。

// 发送端服务
const { context, propagation } = require('@opentelemetry/api');
const output = {};

// 将上下文中的 traceparent 和 tracestate 序列化到输出对象。
//
// 本示例使用活跃链路上下文，也可根据业务场景选用合适的上下文。
propagation.inject(context.active(), output);

const { traceparent, tracestate } = output;
// 随后你可将 traceparent 和 tracestate 数据传递至任何你所使用的、用于跨服务传播上下文的机制中。

在接收服务上，你需要提取 context（例如，从解析的 HTTP 头中），然后将它们设置为当前链路上下文。

// 接收端服务
import {
  type Context,
  propagation,
  trace,
  Span,
  context,
} from '@opentelemetry/api';

// 定义一个接口，用于表示包含 'traceparent' 和 'tracestate' 键的输入对象。
interface Carrier {
  traceparent?: string;
  tracestate?: string;
}

// 假设 "input" 是一个包含 'traceparent' 和 'tracestate' 键的对象。
const input: Carrier = {};

// 将 'traceparent' 和 'tracestate' 数据提取至一个上下文对象中。
//
// 随后你可将此上下文作为你的链路的活跃上下文使用。
let activeContext: Context = propagation.extract(context.active(), input);

let tracer = trace.getTracer('app-name');

let span: Span = tracer.startSpan(
  spanName,
  {
    attributes: {},
  },
  activeContext,
);

// 将创建的 Span 设为反序列化上下文的活跃 Span。
trace.setSpan(activeContext, span);

// 接收端服务
import { context, propagation, trace } from '@opentelemetry/api';

// 假设 "input" 是一个包含 'traceparent' 和 'tracestate' 键的对象。
const input = {};

// 将 'traceparent' 和 'tracestate' 数据提取至一个上下文对象中。
//
// 随后你可将此上下文作为你的链路的活跃上下文使用。
let activeContext = propagation.extract(context.active(), input);

let tracer = trace.getTracer('app-name');

let span = tracer.startSpan(
  spanName,
  {
    attributes: {},
  },
  activeContext,
);

// 将创建的 Span 设为反序列化上下文的活跃 Span。
trace.setSpan(activeContext, span);

从那里开始，当你有一个反序列化的活动上下文时，你可以创建属于来自另一个服务的同一个链路的 Span。

你也可以使用上下文 API 以其他方式修改或设置反序列化的上下文。

自定义协议示例

当你需要手动传播上下文时，一个常见的用例是使用服务间通信的自定义协议。以下示例使用基本的基于文本的 TCP 协议将一个序列化对象从一个服务发送到另一个服务。

首先创建一个名为 propagation-example 的文件夹，并按如下方式初始化依赖项：

npm init -y
npm install @opentelemetry/api @opentelemetry/sdk-node

接下来创建文件 client.js 和 server.js，内容如下：

// client.js
const net = require('net');
const { context, propagation, trace } = require('@opentelemetry/api');

let tracer = trace.getTracer('client');

// 连接到服务器
const client = net.createConnection({ port: 8124 }, () => {
  // 将序列化对象发送至服务器
  let span = tracer.startActiveSpan('send', { kind: 1 }, (span) => {
    const output = {};
    propagation.inject(context.active(), output);
    const { traceparent, tracestate } = output;

    const objToSend = { key: 'value' };

    if (traceparent) {
      objToSend._meta = { traceparent, tracestate };
    }

    client.write(JSON.stringify(objToSend), () => {
      client.end();
      span.end();
    });
  });
});

// server.js
const net = require('net');
const { context, propagation, trace } = require('@opentelemetry/api');

let tracer = trace.getTracer('server');

const server = net.createServer((socket) => {
  socket.on('data', (data) => {
    const message = data.toString();
    // 解析从客户端接收的 JSON 对象
    try {
      const json = JSON.parse(message);
      let activeContext = context.active();
      if (json._meta) {
        activeContext = propagation.extract(context.active(), json._meta);
        delete json._meta;
      }
      span = tracer.startSpan('receive', { kind: 1 }, activeContext);
      trace.setSpan(activeContext, span);
      console.log('Parsed JSON:', json);
    } catch (e) {
      console.error('Error parsing JSON:', e.message);
    } finally {
      span.end();
    }
  });
});

// 监听 8124 端口
server.listen(8124, () => {
  console.log('Server listening on port 8124');
});

启动第一个终端来运行服务器：

$ node server.js
Server listening on port 8124

然后在第二个终端中运行客户端：

node client.js

客户端应立即终止，服务器应输出以下内容：

Parsed JSON: { key: 'value' }

由于到目前为止，该示例仅依赖 OpenTelemetry API，因此所有对该 API 的调用均为空操作指令，客户端与服务端的运行行为也等同于未启用 OpenTelemetry 的状态。

Note

这在你的服务器和客户端代码是库的情况下尤为重要，因为它们应该只使用 OpenTelemetry API。要了解原因，请阅读关于如何为你的库添加插桩的概念页面。

要启用 OpenTelemetry 并查看上下文传播的实际效果，请创建一个名为 instrumentation.js 的附加文件，内容如下：

// instrumentation.mjs
import { NodeSDK } from '@opentelemetry/sdk-node';
import {
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-node';

const sdk = new NodeSDK({
  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
});

sdk.start();

使用此文件来运行服务器和客户端，并启用插桩：

$ node --import ./instrumentation.mjs server.js
Server listening on port 8124

以及

node --import ./instrumentation.mjs client.js

在客户端向服务器发送数据并终止后，你应该在两个终端的控制台输出中看到 Span。

客户端的输出类似于以下内容：

{
  resource: {
    attributes: {
      // ...
    }
  },
  traceId: '4b5367d540726a70afdbaf49240e6597',
  parentId: undefined,
  traceState: undefined,
  name: 'send',
  id: '92f125fa335505ec',
  kind: 1,
  timestamp: 1718879823424000,
  duration: 1054.583,
  // ...
}

服务器的输出类似于以下内容：

{
  resource: {
    attributes: {
      // ...
    }
  },
  traceId: '4b5367d540726a70afdbaf49240e6597',
  parentId: '92f125fa335505ec',
  traceState: undefined,
  name: 'receive',
  id: '53da0c5f03cb36e5',
  kind: 1,
  timestamp: 1718879823426000,
  duration: 959.541,
  // ...
}

与手动示例类似，这些 Span 使用 traceId 和 id、parentId 连接。

下一步

要了解有关传播的更多信息，请阅读传播器 API 规范。

意见反馈

这个页面对您有帮助吗？

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

最后修改 January 8, 2026: [i18n] Update drifted status for localized content (#8767) (9d9fbbe4)