Migrer vers OpenTelemetry Node.js

Lorsque le SDK X-Ray pour Node.js était utilisé, le aws-xray-sdk package devait configurer le SDK X-Ray avec des plug-ins de service ou des règles d'échantillonnage locales avant d'utiliser le SDK pour instrumenter votre code.

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

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

Pour l'exemple de code ci-dessous, vous aurez besoin des dépendances suivantes :

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

Vous devez installer et configurer le OpenTelemetry SDK avant d'exécuter le code de votre application. Cela peut être fait en utilisant l'indicateur —-require. Créez un fichier nommé instrumentation.js, qui contiendra la configuration et l'installation de votre OpenTelemetry instrumentation.

Il est recommandé de configurer les composants suivants :

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

Ensuite, vous pouvez exécuter votre application avec votre OpenTelemetry configuration comme suit :

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

Vous pouvez utiliser les instruments de bibliothèque du OpenTelemetry SDK pour créer automatiquement des étendues pour des bibliothèques telles que le SDK. AWS Leur activation créera automatiquement des intervalles pour les modules tels que le AWS SDK pour JavaScript la version 3. OpenTelemetry offre la possibilité d'activer toutes les instrumentations de bibliothèque ou de spécifier les instrumentations de bibliothèque à activer.

Pour activer toutes les instrumentations, installez le @opentelemetry/auto-instrumentations-node package :

npm install @opentelemetry/auto-instrumentations-node
        

Ensuite, mettez à jour la configuration pour activer toutes les instrumentations de bibliothèque, comme indiqué ci-dessous.

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

...

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

Vous pouvez utiliser l'instrumentation automatique ADOT pour Node.js afin de configurer automatiquement vos OpenTelemetry applications Node.js. En utilisant ADOT Auto-Instrumentation, vous n'avez pas besoin de modifier manuellement le code pour suivre les demandes entrantes ou pour suivre les bibliothèques telles que le AWS SDK ou les clients HTTP. Pour plus d'informations, consultez la section Traçage et métriques avec le AWS distributeur pour l'instrumentation OpenTelemetry JavaScript automatique.

L'instrumentation automatique ADOT pour Node.js prend en charge :

Express.js

Avec le SDK X-Ray pour suivre les requêtes HTTP entrantes reçues par les applications Express.js, les deux AWSXRay.express.openSegment(<name>) intergiciels AWSXRay.express.closeSegment() devaient encapsuler toutes les routes définies afin de les tracer.

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

...

app.use(xrayExpress.closeSegment());
          

Restifier

Pour suivre les requêtes HTTP entrantes reçues par Restify les applications, le middleware du SDK X-Ray a été utilisé en exécutant enable depuis le aws-xray-sdk-restify module sur le serveur 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

Le suivi des demandes entrantes Express.js est assuré par l'instrumentation OpenTelemetry HTTP et l'instrumentation OpenTelemetry express. Installez les dépendances suivantes avec npm :

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

Mettez à jour la configuration du OpenTelemetry SDK pour activer l'instrumentation pour le module 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(),
  ],
});
          

Restifier

Pour les applications Restify, vous aurez besoin de l'instrumentation OpenTelemetry Restify. Installez la dépendance suivante :

npm install --save @opentelemetry/instrumentation-restify
          

Mettez à jour la configuration du OpenTelemetry SDK pour activer l'instrumentation pour le module restify :

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

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

Pour instrumenter les AWS demandes sortantes depuis le AWS SDK, vous avez instrumenté les clients comme dans l'exemple suivant :

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

La prise en charge du suivi des appels du AWS SDK en aval vers DynamoDB, Amazon S3 et d'autres est fournie par OpenTelemetry AWS l'instrumentation du SDK. Installez la dépendance suivante avec npm :

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

Mettez à jour la configuration du OpenTelemetry SDK avec l'instrumentation du AWS SDK.

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

const sdk = new NodeSDK({
  ...

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

Pour instrumenter les requêtes HTTP sortantes avec X-Ray, il était nécessaire d'instrumenter les clients. Par exemple, voir ci-dessous.

Clients HTTP individuels

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

Tous les clients HTTP (globaux)

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

La prise en charge du suivi pour les clients HTTP Node.js est fournie par l'instrumentation OpenTelemetry HTTP. Installez la dépendance suivante avec npm :

npm install --save @opentelemetry/instrumentation-http
      

Mettez à jour la configuration du OpenTelemetry SDK comme suit :

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

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

À l'aide de X-Ray, le code aws-xray-sdk du package était nécessaire pour créer manuellement des segments et leurs sous-segments secondaires afin de suivre votre application.

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

Vous pouvez créer et utiliser des intervalles personnalisés pour surveiller les performances des activités internes qui ne sont pas capturées par les bibliothèques d'instrumentation. Notez que seules les plages de type Server sont converties en segments X-Ray, toutes les autres plages sont converties en sous-segments de X-Ray. Pour plus d’informations, consultez Segments.

Vous aurez besoin d'une instance Tracer après avoir configuré le OpenTelemetry SDK dans Tracing Setup pour créer des Spans. Vous pouvez créer autant d'instances de Tracer que nécessaire, mais il est courant d'avoir un seul Tracer pour l'ensemble d'une application.

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

Ajouter des annotations et des métadonnées aux traces avec OpenTelemetry le SDK

Vous pouvez également ajouter des paires clé-valeur personnalisées en tant qu'attributs dans vos spans. Notez que par défaut, tous ces attributs d'étendue seront convertis en métadonnées dans les données brutes de X-Ray. Pour vous assurer qu'un attribut est converti en annotation et non en métadonnées, ajoutez la clé de l'attribut à la liste de l'aws.xray.annotationsattribut. Pour plus d'informations, consultez 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();
  });
      

Après avoir activé Active Tracing pour votre fonction Lambda, le SDK X-Ray était requis sans configuration supplémentaire. Lambda crée un segment représentant l'invocation du gestionnaire Lambda, et vous avez créé des sous-segments ou des bibliothèques d'instruments à l'aide du SDK X-Ray sans aucune configuration supplémentaire.

Vous pouvez automatiquement instrumenter votre Lambda avec des couches AWS Lambda vendues. Il existe deux solutions :

Création manuelle de spans avec l'instrumentation Lambda

Bien que la couche JavaScript Lambda ADOT fournisse une instrumentation automatique pour votre fonction Lambda, vous pourriez avoir besoin d'effectuer une instrumentation manuelle dans votre Lambda, par exemple, pour fournir des données personnalisées ou pour instrumenter du code au sein de la fonction Lambda elle-même qui n'est pas couvert par les instrumentations de bibliothèque.

Pour effectuer une instrumentation manuelle parallèlement à l'instrumentation automatique, vous devez ajouter @opentelemetry/api une dépendance. Il est recommandé que la version de cette dépendance soit la même version de la même dépendance que celle utilisée par le JavaScript SDK ADOT. Vous pouvez utiliser l' OpenTelemetry API pour créer manuellement des intervalles dans votre fonction Lambda.

Pour ajouter la @opentelemetry/api dépendance à l'aide de NPM :

npm install @opentelemetry/api