遷移至 OpenTelemetry Node.js

使用適用於 Node.js 的 X-Ray 開發套件時，需要使用 aws-xray-sdk套件來設定 X-Ray 開發套件搭配服務外掛程式或本機取樣規則，然後再使用 開發套件來檢測您的程式碼。

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，才能執行應用程式程式碼。這可以透過使用 –-require 旗標來完成。建立名為 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 程式庫檢測，自動建立 AWS SDK 等程式庫的範圍。啟用這些項目會自動建立模組的範圍，例如適用於 JavaScript 的 AWS SDK v3。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-Instrumentation，您不需要手動變更程式碼來追蹤傳入的請求，或追蹤 AWS SDK 或 HTTP 用戶端等程式庫。如需詳細資訊，請參閱使用 AWS Distro for OpenTelemetry JavaScript Auto-Instrumentation 追蹤 和 指標。

Node.js 的 ADOT 自動檢測支援：

Express.js

使用 X-Ray 開發套件追蹤 Express.js 應用程式收到的傳入 HTTP 請求，AWSXRay.express.closeSegment()需要兩個中介軟體AWSXRay.express.openSegment(<name>)和 來包裝所有定義的路由，以便追蹤它們。

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

...

app.use(xrayExpress.closeSegment());
          

重新設定

若要追蹤Restify應用程式收到的傳入 HTTP 請求，透過從 Restify Server 上的 aws-xray-sdk-restify 模組執行啟用，使用 X-Ray 開發套件的中介軟體：

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

追蹤 的傳入請求支援Express.js是由 OpenTelemetry HTTP 檢測和 OpenTelemetry Express 檢測提供。使用 安裝下列相依性npm：

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

更新 OpenTelemetry SDK 組態以啟用快速模組的檢測：

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 應用程式，您將需要 OpenTelemetry Restify 檢測。安裝下列相依性：

npm install --save @opentelemetry/instrumentation-restify
          

更新 OpenTelemetry SDK 組態以啟用 Restify 模組的檢測：

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

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

若要檢測來自 AWS SDK 的傳出 AWS 請求，您檢測了用戶端，如下列範例所示：

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!',
}));
      

追蹤對 DynamoDB、Amazon S3 和其他 的下游 AWS SDK 呼叫支援，是由 OpenTelemetry AWS SDK 檢測提供。使用 安裝下列相依性npm：

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

使用 SDK 檢測更新 OpenTelemetry AWS SDK 組態。

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');

追蹤 Node.js HTTP 用戶端的支援是由 OpenTelemetry HTTP 檢測提供。使用 安裝下列相依性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 以建立跨度之後，您將需要一個 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 函數啟用 Active Tracing 後，需要 X-Ray 開發套件，無需額外的組態。Lambda 會建立代表 Lambda 處理常式調用的區段，而且您使用 X-Ray SDK 建立子區段或檢測程式庫，而不需要任何其他組態。

您可以使用 AWS 付費 Lambda 層自動檢測 Lambda。有兩種解決方案：

使用 Lambda 檢測手動建立 Spans

雖然 ADOT JavaScript Lambda Layer 為您的 Lambda 函數提供自動檢測，但您可能會發現需要在 Lambda 中執行手動檢測，例如，提供自訂資料或在程式庫檢測未涵蓋的 Lambda 函數本身內檢測程式碼。

若要搭配自動檢測執行手動檢測，您需要新增 @opentelemetry/api做為相依性。此相依性的版本建議與 ADOT JavaScript SDK 使用的相同相依性版本相同。您可以使用 OpenTelemetry API 在 Lambda 函數中手動建立跨度。

若要使用 NPM 新增@opentelemetry/api相依性：

npm install @opentelemetry/api