OpenTelemetry Node.js への移行

X-Ray SDK for Node.js を使用した場合、SDK を使用してコードを計測する前に、aws-xray-sdkX-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 をセットアップして設定する必要があります。これは、–-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 などのライブラリのスパンを自動的に作成できます。これらを有効にすると、 AWS SDK for JavaScript 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

Express.js アプリケーションによって受信された HTTP リクエストを追跡する X-Ray SDK では、2 つのミドルウェアAWSXRay.express.openSegment(<name>)と は、定義されたルートをすべてラップしてトレースする必要がありAWSXRay.express.closeSegment()ました。

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

...

app.use(xrayExpress.closeSegment());
          

復元

Restify アプリケーションによって受信された HTTP リクエストをトレースするために、X-Ray SDK のミドルウェアは、Restify Server の aws-xray-sdk-restify モジュールから enable を実行して使用されました。

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 設定を更新して、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 アプリケーションの場合は、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 計測によって提供されます。 Amazon S3 で次の依存関係をインストールします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 Instrumentation によって提供されます。で次の依存関係をインストールします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 インスタンスを作成できますが、アプリケーション全体に 1 つの 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 raw データ内のメタデータに変換されることに注意してください。属性がメタデータではなく注釈に変換されるようにするには、属性のリストに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 を使用してサブセグメントまたは計測ライブラリを作成しました。

AWS 販売された Lambda レイヤーを使用して Lambda を自動的に計測できます。解決策は 2 つあります。

Lambda 計測を使用したスパンの手動作成

ADOT JavaScript Lambda Layer は Lambda 関数の自動計測を提供しますが、カスタムデータの提供や、ライブラリ計測の対象ではない Lambda 関数自体内のコードの計測など、Lambda で手動計測を実行する必要がある場合があります。

自動計測とともに手動計測を実行するには、 を依存関係@opentelemetry/apiとして追加する必要があります。この依存関係のバージョンは、ADOT JavaScript SDK で使用されるのと同じ依存関係のバージョンにすることをお勧めします。OpenTelemetry API を使用して、Lambda 関数にスパンを手動で作成できます。

NPM を使用して@opentelemetry/api依存関係を追加するには：

npm install @opentelemetry/api