迁移到 OpenTelemetry Node.js

使用适用于 Node.js 的 X-Ray SDK 时，aws-xray-sdk软件包需要在使用 SDK 对您的代码进行检测之前，使用服务插件或本地采样规则配置 X-Ray SDK。

var AWSXRay = require('aws-xray-sdk');

AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]);
AWSXRay.middleware.setSamplingRules(<path to file>);
        

对于下面的代码示例，您将需要以下依赖项：

npm install --save \
  @opentelemetry/api \
  @opentelemetry/sdk-node \
  @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/propagator-aws-xray \
  @opentelemetry/resource-detector-aws
        

在运行应用程序代码之前，必须设置和配置 OpenTelemetry SDK。这可以通过使用 —-req uire 标志来完成。创建一个名为 instrumentation.js 的文件，其中将包含您的 OpenTelemetry 仪器配置和设置。

建议您配置以下组件：

/*instrumentation.js*/
// Require dependencies
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { AWSXRayPropagator } = require("@opentelemetry/propagator-aws-xray");
const { detectResources } = require('@opentelemetry/resources');
const { awsEc2Detector } = require('@opentelemetry/resource-detector-aws');

const resource = detectResources({
    detectors: [awsEc2Detector],
});
 
const _traceExporter = new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces'
});

const sdk = new NodeSDK({
    resource: resource,
    textMapPropagator: new AWSXRayPropagator(),
    traceExporter: _traceExporter
});

sdk.start();
        

然后，你可以用你的 OpenTelemetry 设置来运行你的应用程序，比如：

node --require ./instrumentation.js app.js
        

您可以使用 OpenTelemetry SDK 库工具自动为 SDK 等库创建跨度。 Amazon 启用这些功能将自动为模块（例如 JavaScript v3 版 Amazon SDK）创建跨度。 OpenTelemetry 提供了启用所有库乐器或指定要启用哪些库乐器的选项。

要启用所有工具，请安装软件包：@opentelemetry/auto-instrumentations-node

npm install @opentelemetry/auto-instrumentations-node
        

接下来，更新配置以启用所有库工具，如下所示。

const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');

...

const sdk = new NodeSDK({
    resource: resource,
     instrumentations: [getNodeAutoInstrumentations()],
     textMapPropagator: new AWSXRayPropagator(),
    traceExporter: _traceExporter
});

你可以使用适用于 Node.js 的 ADOT 自动检测来自动为你的 Node.js OpenTelemetry 应用程序进行配置。通过使用 ADOT Auto-Instrumention，您无需手动更改代码即可跟踪传入的请求或跟踪 Amazon SDK 或 HTTP 客户端等库。有关更多信息，请参阅使用 OpenTelemetry JavaScript 自动检测 Amazon 发行版进行跟踪和指标。

适用于 Node.js 的 ADOT 自动检测支持：

Express.js

使用 X-Ray SDK 来跟踪 Express.js 应用程序收到的传入 HTTP 请求，两个中间件AWSXRay.express.openSegment(<name>)和AWSXRay.express.closeSegment()需要封装所有定义的路由才能跟踪它们。

app.use(xrayExpress.openSegment('defaultName'));

...

app.use(xrayExpress.closeSegment());
          

Restify

为了跟踪Restify应用程序收到的传入 HTTP 请求，使用了 X-Ray SDK 中的中间件，方法是从 Restify aws-xray-sdk-restify 服务器上的模块运行启用：

var AWSXRay = require('aws-xray-sdk');
var AWSXRayRestify = require('aws-xray-sdk-restify');

var restify = require('restify');
var server = restify.createServer();
AWSXRayRestify.enable(server, 'MyApp'));
          

Express.js

OpenTelemetry HTTP 检测和OpenTelemetry 快速检测Express.js为传入的请求提供跟踪支持。使用以下方法安装以下依赖项npm：

npm install --save @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express
          

更新 OpenTelemetry SDK 配置以启用对 express 模块的检测：

const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
...

const sdk = new NodeSDK({
  ...
  
  instrumentations: [
    ...
    // Express instrumentation requires HTTP instrumentation
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
  ],
});
          

Restify

对于 Restify 应用程序，你需要使用 OpenTelemetry Restify 工具。安装以下依赖项：

npm install --save @opentelemetry/instrumentation-restify
          

更新 OpenTelemetry SDK 配置以启用 restify 模块的检测功能：

const { RestifyInstrumentation } = require('@opentelemetry/instrumentation-restify');
...

const sdk = new NodeSDK({
  ...
  
  instrumentations: [
    ...
    new RestifyInstrumentation(),
  ],
});
          

要检测来自 Amazon SDK 的传出 Amazon 请求，您需要对客户端进行检测，如下例所示：

import { S3, PutObjectCommand } from '@aws-sdk/client-s3';

const s3 = AWSXRay.captureAWSv3Client(new S3({}));

await s3.send(new PutObjectCommand({
  Bucket: bucketName,
  Key: keyName,
  Body: 'Hello!',
}));
      

对下游 Amazon DynamoDB、Amazon S3 和其他软件开发工具包调用的跟踪支持由 OpenTelemetry Amazon 软件开发工具包工具包工具提供。使用以下方法安装以下依赖项npm：

npm install --save @opentelemetry/instrumentation-aws-sdk
      

使用 S OpenTelemetry DK 工具更新 S Amazon DK 配置。

import { AwsInstrumentation } from '@opentelemetry/instrumentation-aws-sdk';
...

const sdk = new NodeSDK({
  ...

  instrumentations: [
    ...
    new AwsInstrumentation()
  ],
});
      

要使用 X-Ray 检测传出的 HTTP 请求，需要检测客户端。例如，见下文。

单个 HTTP 客户端

var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
      

所有 HTTP 客户端（全局）

var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');

HTTP 工具为 Node.js HTT OpenTelemetry P 客户端提供跟踪支持。使用以下方法安装以下依赖项npm：

npm install --save @opentelemetry/instrumentation-http
      

按如下方式更新 OpenTelemetry SDK 配置：

const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
...

const sdk = new NodeSDK({
  ...
  
  instrumentations: [
    ...
    new HttpInstrumentation(),
  ],
});
      

使用 X-Ray，需要使用aws-xray-sdk软件包代码来手动创建区段及其子子分段来跟踪您的应用程序。

var AWSXRay = require('aws-xray-sdk');

AWSXRay.enableManualMode();

var segment = new AWSXRay.Segment('myApplication');

captureFunc('1', function(subsegment1) {
  captureFunc('2', function(subsegment2) {

  }, subsegment1);
}, segment);

segment.close();
segment.flush();
      

您可以创建和使用自定义跨度来监控未被仪器库捕获的内部活动的性能。请注意，只有服务器类型的跨度才会转换为 X-Ray 分段，所有其他跨度都会转换为 X-Ray 子分段。有关更多信息，请参阅分段。

在跟踪设置中配置 OpenTelemetry SDK 以创建 Span 之后，您将需要一个 Tracer 实例。您可以根据需要创建任意数量的 Tracer 实例，但通常为整个应用程序使用一个 Tracer。

const { trace, SpanKind } = require('@opentelemetry/api');

// Get a tracer instance
const tracer = trace.getTracer('your-tracer-name');

...

  // This span will appear as a segment in X-Ray
  tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
    // Do work here

    // This span will appear as a subsegment in X-Ray
    tracer.startActiveSpan('operation2', { kind: SpanKind.INTERNAL }, innerSpan => {
      // Do more work here

      innerSpan.end();
    });
    span.end();
  });
      

使用 OpenTelemetry SDK 向跟踪添加注释和元数据

您还可以将自定义键值对添加为跨度中的属性。请注意，默认情况下，所有这些跨度属性都将转换为 X-Ray 原始数据中的元数据。为确保将属性转换为注释而不是元数据，请将该属性的键添加到aws.xray.annotations属性列表中。有关更多信息，请参见启用自定义 X-Ray 注释。

  tracer.startActiveSpan('server', { kind: SpanKind.SERVER }, span => {
    span.setAttribute('metadataKey', 'metadataValue');
    span.setAttribute('annotationKey', 'annotationValue');

    // The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
    span.setAttribute('aws.xray.annotations', ['annotationKey']);

    // Do work here

    span.end();
  });
      

为 Lambda 函数启用主动跟踪后，无需额外配置即可使用 X-Ray SDK。Lambda 创建了一个表示 Lambda 处理程序调用的区段，而您使用 X-Ray SDK 创建了子分段或仪器库，而无需进行任何其他配置。

您可以使用已打开的 Lambda 图层自动检测您的 Lambda Amazon 。有两种解决方案：

使用 Lambda 工具手动创建跨度

虽然 ADOT Lamb JavaScript da 层为您的 Lambda 函数提供了自动检测，但您可能会发现需要在 Lambda 中执行手动检测，例如，提供自定义数据或在 Lambda 函数本身中检测库工具未涵盖的代码。

要在自动检测的同时执行手动插入，您需要添加@opentelemetry/api为依赖项。建议此依赖项的版本与 ADOT JavaScript SDK 使用的相同依赖项的版本相同。您可以使用 OpenTelemetry API 在 Lambda 函数中手动创建跨度。

要使用 NPM 添加@opentelemetry/api依赖项，请执行以下操作：

npm install @opentelemetry/api