OpenTelemetry Node.js への移行

X-Ray SDK for Node.js を使用する場合、SDK を使用してコードを計装する前に、X-Ray SDK をサービスプラグインまたはローカルサンプリングルールで設定するために aws-xray-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

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

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

...

app.use(xrayExpress.closeSegment());
          

Restify

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

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 計装によって提供されます。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();
      

カスタムスパンを作成して使用することで、計装ライブラリでキャプチャされない内部アクティビティのパフォーマンスをモニタリングできます。Server タイプのスパンのみが X-Ray セグメントに変換され、他のすべてのスパンは X-Ray サブセグメントに変換されることに注意してください。詳細については、「セグメント」を参照してください。

トレースセットアップで OpenTelemetry SDK を設定してスパンを作成すると、トレーサーインスタンスが必要になります。必要に応じていくつでもトレーサーインスタンスを作成できますが、アプリケーション全体で 1 つのトレーサーを持つことが一般的です。

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 属性のリストに追加します。詳細については、「Enable The Customized X-Ray Annotations」を参照してください。

  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 レイヤーは Lambda 関数の自動計装を提供しますが、Lambda で手動計装を実行する必要がある場合もあります。例えば、カスタムデータの提供やライブラリ計装の対象ではない Lambda 関数内のコードの計装などです。

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

NPM を使用して @opentelemetry/api 依存関係を追加する方法

npm install @opentelemetry/api