Migrasi ke Node.js OpenTelemetry

Ketika X-Ray SDK untuk Node.js digunakan, aws-xray-sdk paket diperlukan untuk mengonfigurasi X-Ray SDK dengan plug-in layanan atau aturan pengambilan sampel lokal sebelum menggunakan SDK untuk instrumen kode Anda.

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

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

Untuk contoh kode di bawah ini, Anda memerlukan dependensi berikut:

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

Anda harus mengatur dan mengkonfigurasi OpenTelemetry SDK sebelum menjalankan kode aplikasi Anda. Ini dapat dilakukan dengan menggunakan tanda —-require. Buat file bernama instrumentation.js, yang akan berisi konfigurasi dan pengaturan OpenTelemetry instrumentasi Anda.

Disarankan agar Anda mengkonfigurasi komponen-komponen berikut:

/*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();
        

Kemudian, Anda dapat menjalankan aplikasi Anda dengan OpenTelemetry pengaturan Anda seperti:

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

Anda dapat menggunakan instrumentasi pustaka OpenTelemetry SDK untuk membuat rentang pustaka secara otomatis seperti SDK. AWS Mengaktifkan ini akan secara otomatis membuat rentang untuk modul seperti AWS SDK untuk v3. JavaScript OpenTelemetry menyediakan opsi untuk mengaktifkan semua instrumentasi perpustakaan atau menentukan instrumentasi perpustakaan mana yang akan diaktifkan.

Untuk mengaktifkan semua instrumentasi, instal paket: @opentelemetry/auto-instrumentations-node

npm install @opentelemetry/auto-instrumentations-node
        

Selanjutnya, perbarui konfigurasi untuk mengaktifkan semua instrumentasi perpustakaan seperti yang ditunjukkan di bawah ini.

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

...

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

Anda dapat menggunakan instrumentasi otomatis ADOT untuk Node.js untuk mengkonfigurasi OpenTelemetry secara otomatis untuk aplikasi Node.js Anda. Dengan menggunakan ADOT Auto-Instrumentation, Anda tidak perlu membuat perubahan kode manual untuk melacak permintaan yang masuk, atau untuk melacak pustaka seperti klien SDK atau HTTP. AWS Untuk informasi selengkapnya, lihat Menelusuri dan metrik dengan AWS Distro untuk Instrumentasi Otomatis. OpenTelemetry JavaScript

Instrumentasi otomatis ADOT untuk Node.js mendukung:

Express.js

Dengan X-Ray SDK untuk melacak permintaan HTTP masuk yang diterima oleh aplikasi Express.js, kedua middlewares AWSXRay.express.openSegment(<name>) dan AWSXRay.express.closeSegment() diminta untuk membungkus semua rute yang Anda tentukan untuk melacaknya.

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

...

app.use(xrayExpress.closeSegment());
          

Membantah

Untuk melacak permintaan HTTP masuk yang diterima oleh Restify aplikasi, middleware dari X-Ray SDK digunakan dengan menjalankan enable dari aws-xray-sdk-restify modul di Server 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

Menelusuri dukungan untuk permintaan masuk Express.js disediakan oleh instrumentasi OpenTelemetry HTTP dan OpenTelemetry instrumentasi ekspres. Instal dependensi berikut dengan: npm

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

Perbarui Konfigurasi OpenTelemetry SDK untuk mengaktifkan instrumentasi untuk modul ekspres:

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(),
  ],
});
          

Membantah

Untuk aplikasi Restify, Anda memerlukan instrumentasi OpenTelemetry Restify. Instal ketergantungan berikut:

npm install --save @opentelemetry/instrumentation-restify
          

Perbarui Konfigurasi OpenTelemetry SDK untuk mengaktifkan instrumentasi untuk modul restify:

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

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

Untuk menginstrumentasi AWS permintaan keluar dari AWS SDK, Anda menginstrumentasi klien seperti contoh berikut:

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

Menelusuri dukungan untuk panggilan AWS SDK hilir ke DynamoDB, Amazon S3, dan lainnya disediakan oleh instrumentasi SDK. OpenTelemetry AWS Instal ketergantungan berikut dengannpm:

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

Perbarui Konfigurasi OpenTelemetry SDK dengan instrumentasi AWS SDK.

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

const sdk = new NodeSDK({
  ...

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

Untuk instrumen permintaan HTTP keluar dengan X-Ray, itu diperlukan untuk instrumen klien. Misalnya, lihat di bawah.

Klien HTTP individu

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

Semua klien HTTP (global)

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

Menelusuri dukungan untuk klien HTTP Node.js disediakan oleh Instrumentasi OpenTelemetry HTTP. Instal ketergantungan berikut dengannpm:

npm install --save @opentelemetry/instrumentation-http
      

Perbarui Konfigurasi OpenTelemetry SDK sebagai berikut:

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

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

Menggunakan X-Ray, kode aws-xray-sdk paket diperlukan untuk secara manual membuat segmen dan sub-segmen anak mereka untuk melacak aplikasi Anda.

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

Anda dapat membuat dan menggunakan rentang kustom untuk memantau kinerja aktivitas internal yang tidak ditangkap oleh pustaka instrumentasi. Perhatikan bahwa hanya rentang jenis Server yang diubah menjadi segmen X-Ray, semua rentang lainnya diubah menjadi sub-segmen X-Ray. Untuk informasi selengkapnya, lihat Segmen.

Anda akan memerlukan instance Tracer setelah mengonfigurasi OpenTelemetry SDK di Tracing Setup untuk membuat Span. Anda dapat membuat instance Tracer sebanyak yang diperlukan, tetapi biasanya memiliki satu Tracer untuk seluruh aplikasi.

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();
  });
      

Menambahkan anotasi dan metadata ke jejak dengan SDK OpenTelemetry

Anda juga dapat menambahkan pasangan nilai kunci kustom sebagai atribut dalam rentang Anda. Perhatikan bahwa secara default, semua atribut rentang ini akan diubah menjadi metadata dalam data mentah X-Ray. Untuk memastikan bahwa atribut diubah menjadi anotasi dan bukan metadata, tambahkan kunci atribut ke daftar atribut. aws.xray.annotations Untuk informasi selengkapnya, lihat Mengaktifkan Anotasi X-Ray yang Disesuaikan.

  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();
  });
      

Setelah Anda mengaktifkan Active Tracing untuk fungsi Lambda Anda, X-Ray SDK diperlukan tanpa konfigurasi tambahan. Lambda membuat segmen yang mewakili pemanggilan penangan Lambda, dan Anda membuat sub-segmen atau pustaka instrumen menggunakan X-Ray SDK tanpa konfigurasi tambahan apa pun.

Anda dapat secara otomatis menginstruksikan Lambda Anda dengan lapisan Lambda AWS yang dijual. Ada dua solusi:

Membuat Span secara manual dengan instrumentasi Lambda

Sementara ADOT JavaScript Lambda Layer menyediakan instrumentasi otomatis untuk fungsi Lambda Anda, Anda mungkin menemukan kebutuhan untuk melakukan instrumentasi manual di Lambda Anda, misalnya, untuk menyediakan data kustom atau kode instrumen dalam fungsi Lambda itu sendiri yang tidak tercakup oleh instrumentasi perpustakaan.

Untuk melakukan instrumentasi manual bersama instrumentasi otomatis, Anda perlu menambahkan @opentelemetry/api sebagai ketergantungan. Versi dependensi ini direkomendasikan untuk menjadi versi yang sama dari dependensi yang sama yang digunakan oleh JavaScript ADOT SDK. Anda dapat menggunakan OpenTelemetry API untuk membuat bentang secara manual di fungsi Lambda Anda.

Untuk menambahkan @opentelemetry/api ketergantungan menggunakan NPM:

npm install @opentelemetry/api