OpenTelemetry Node.js로 마이그레이션

Node.js용 X-Ray SDK를 사용할 때 SDK를 사용하여 코드를 계측하기 전에 aws-xray-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를 설정하고 구성해야 합니다. 이 작업은 --require 플래그를 사용하여 수행할 수 있습니다. OpenTelemetry 계측 구성 및 설정이 포함된 instrumentation.js라는 파일을 생성합니다.

다음 구성 요소를 구성하는 것이 좋습니다.

/*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를 사용하면 두 미들웨어 AWSXRay.express.openSegment(<name>) 및 AWSXRay.express.closeSegment()가 이를 추적하기 위해 정의된 모든 경로를 래핑해야 했습니다.

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

...

app.use(xrayExpress.closeSegment());
          

재지정

Restify 애플리케이션에서 수신한 HTTP 요청을 추적하기 위해 Restify 서버의 aws-xray-sdk-restify 모듈에서 활성화를 실행하여 X-Ray SDK의 미들웨어를 사용했습니다.

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
          

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 구성을 업데이트하여 재지정 모듈에 대한 계측을 활성화합니다.

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 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를 사용하는 것이 일반적입니다.

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를 사용하여 하위 세그먼트 또는 계측 라이브러리를 생성했습니다.

AWS 벤딩된 Lambda 계층으로 Lambda를 자동으로 계측할 수 있습니다. 두 가지 해결 방법이 있습니다.

Lambda 계측을 사용하여 수동으로 스팬 생성

ADOT JavaScript Lambda 계층은 Lambda 함수에 대한 자동 계측을 제공하지만, 예를 들어 사용자 지정 데이터를 제공하거나 라이브러리 계측에서 다루지 않는 Lambda 함수 자체 내의 코드를 계측하기 위해 Lambda에서 수동 계측을 수행해야 할 수 있습니다.

자동 계측과 함께 수동 계측을 수행하려면를 종속성@opentelemetry/api으로 추가해야 합니다. 이 종속성의 버전은 ADOT JavaScript SDK에서 사용하는 것과 동일한 종속성의 버전인 것이 좋습니다. OpenTelemetry API를 사용하여 Lambda 함수에서 스팬을 수동으로 생성할 수 있습니다.

NPM을 사용하여 @opentelemetry/api 종속성을 추가하려면:

npm install @opentelemetry/api