Migrare a Node.js OpenTelemetry

Questa sezione spiega come migrare le applicazioni Node.js da X-Ray SDK a. OpenTelemetry Descrive gli approcci di strumentazione sia automatici che manuali e fornisce esempi specifici per casi d'uso comuni.

L'SDK X-Ray Node.js consente di strumentare manualmente le applicazioni Node.js per il tracciamento. Questa sezione fornisce esempi di codice per la migrazione da OpenTelemetry X-Ray alla strumentazione.

Soluzioni di strumentazione automatica a codice zero

Per tracciare le richieste con X-Ray SDK per Node.js, è necessario modificare il codice dell'applicazione. Con OpenTelemetry, puoi utilizzare soluzioni di strumentazione automatica a codice zero per tracciare le richieste.

Strumentazione automatica a codice zero con strumentazione automatica basata. OpenTelemetry

1. Utilizzo della strumentazione automatica AWS Distro for OpenTelemetry (ADOT) per Node.js: per la strumentazione automatica per l'applicazione Node.js, vedere Tracciamento e metriche con la distribuzione per la strumentazione automatica. AWS OpenTelemetry JavaScript

   (Facoltativo) È inoltre possibile abilitare CloudWatch Application Signals quando si attivano automaticamente le applicazioni AWS con la strumentazione JavaScript automatica ADOT per monitorare lo stato attuale delle applicazioni e tenere traccia delle prestazioni delle applicazioni a lungo termine rispetto agli obiettivi aziendali. Application Signals ti offre una visione unificata e incentrata sulle applicazioni di applicazioni, servizi e dipendenze e ti aiuta a monitorare e valutare lo stato delle applicazioni. Per ulteriori informazioni, consulta Application Signals.

2. Utilizzo della strumentazione automatica a OpenTelemetry JavaScript codice zero: per la strumentazione automatica con, vedere strumentazione a codice zero. OpenTelemetry JavaScript JavaScript

Soluzioni di strumentazione manuale

Tracing setup with X-Ray SDK

Quando si utilizzava X-Ray SDK per Node.js, era necessario configurare il aws-xray-sdk pacchetto X-Ray SDK con plug-in di servizio o regole di campionamento locali prima di utilizzare l'SDK per strumentare il codice.

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

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

Tracing setup with OpenTelemetry SDK

Nota

AWS Il campionamento remoto a raggi X non è attualmente disponibile per la configurazione per JS. OpenTelemetry Tuttavia, il supporto per il campionamento remoto a raggi X è attualmente disponibile tramite ADOT Auto-Instrumentation for Node.js.

Per l'esempio di codice riportato di seguito, sono necessarie le seguenti dipendenze:

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

È necessario impostare e configurare l' OpenTelemetry SDK prima di eseguire il codice dell'applicazione. Questa operazione può essere eseguita utilizzando il flag —-require. Create un file chiamato instrumentation.js, che conterrà la configurazione e la configurazione della OpenTelemetry strumentazione.

Si consiglia di configurare i seguenti componenti:

• OTLPTraceEsportatore: necessario per esportare le tracce nell'Agent/ Collector CloudWatch OpenTelemetry

• AWSXRayPropagatore: necessario per propagare il Trace Context ai AWS servizi integrati con X-Ray

• Rilevatori di risorse (ad esempio, Amazon EC2 Resource Detector): per rilevare i metadati dell'host che esegue l'applicazione

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

Quindi, puoi eseguire l'applicazione con la tua configurazione, ad esempio: OpenTelemetry

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

Puoi utilizzare la strumentazione della libreria OpenTelemetry SDK per creare automaticamente intervalli per librerie come l'SDK. AWS Abilitandoli si creeranno automaticamente degli intervalli per moduli come l'SDK per la v3. AWS JavaScript OpenTelemetry offre la possibilità di abilitare tutte le strumentazioni della libreria o specificare quali strumentazioni della libreria abilitare.

Per abilitare tutte le strumentazioni, installa il pacchetto: @opentelemetry/auto-instrumentations-node

npm install @opentelemetry/auto-instrumentations-node
        

Successivamente, aggiorna la configurazione per abilitare tutte le strumentazioni della libreria come mostrato di seguito.

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

...

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

Tracing setup with ADOT auto-instrumentation for Node.js

È possibile utilizzare la strumentazione automatica ADOT per Node.js OpenTelemetry per configurare automaticamente le applicazioni Node.js. Utilizzando ADOT Auto-Instrumentation, non è necessario apportare modifiche manuali al codice per tracciare le richieste in arrivo o tracciare librerie come i client SDK o HTTP. AWS Per ulteriori informazioni, consulta Tracciamento e metriche con la distribuzione per Auto-Instrumentation. AWS OpenTelemetry JavaScript

La strumentazione automatica ADOT per Node.js supporta:

• Campionamento remoto a raggi X tramite variabile di ambiente — export OTEL_TRACES_SAMPLER=xray

• Propagazione contestuale delle tracce X-Ray (abilitata per impostazione predefinita)

• Rilevamento delle risorse (il rilevamento delle risorse per gli ambienti Amazon EC2, Amazon ECS e Amazon EKS è abilitato per impostazione predefinita)

• Strumentazioni di libreria automatiche per tutte le OpenTelemetry strumentazioni supportate, che possono essere disabled/enabled utilizzate selettivamente tramite variabili di ambiente OTEL_NODE_ENABLED_INSTRUMENTATIONS OTEL_NODE_DISABLED_INSTRUMENTATIONS

• Creazione manuale di Spans

Tracciamento delle richieste in arrivo

With X-Ray SDK

Express.js

Grazie all'SDK X-Ray per tracciare le richieste HTTP in entrata ricevute dalle applicazioni Express.js, i due middleware AWSXRay.express.openSegment(<name>) e i due middleware AWSXRay.express.closeSegment() dovevano avvolgere tutte le rotte definite per poterle tracciare.

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

...

app.use(xrayExpress.closeSegment());
          

Restifica

Per tracciare le richieste HTTP in entrata ricevute dalle Restify applicazioni, è stato utilizzato il middleware dell'X-Ray SDK eseguendo enable dal modulo sul aws-xray-sdk-restify 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'));
          

With OpenTelemetry SDK

Express.js

Il supporto di tracciamento per le richieste in entrata di Express.js è fornito dalla strumentazione OpenTelemetry HTTP e dalla strumentazione express. OpenTelemetry Installa le seguenti dipendenze con: npm

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

Aggiorna la configurazione OpenTelemetry SDK per abilitare la strumentazione per il modulo 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(),
  ],
});
          

Restifica

Per le applicazioni Restify, avrai bisogno della strumentazione OpenTelemetry Restify. Installa la seguente dipendenza:

npm install --save @opentelemetry/instrumentation-restify
          

Aggiorna la configurazione OpenTelemetry SDK per abilitare la strumentazione per il modulo restify:

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

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

AWS Strumentazione SDK V3 JavaScript

With X-Ray SDK

Per strumentare AWS le richieste in uscita dall' AWS SDK, avete utilizzato client strumentati come nell'esempio seguente:

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

With OpenTelemetry SDK

Il supporto di tracciamento per le chiamate AWS SDK downstream a DynamoDB, Amazon S3 e altri è fornito dalla strumentazione SDK. OpenTelemetry AWS npmInstalla la seguente dipendenza con:

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

Aggiorna la configurazione OpenTelemetry SDK con la strumentazione AWS SDK.

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

const sdk = new NodeSDK({
  ...

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

Analisi delle chiamate HTTP in uscita

With X-Ray SDK

Per strumentare le richieste HTTP in uscita con X-Ray, era necessario strumentare i client. Ad esempio, vedi sotto.

Client HTTP individuali

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

Tutti i client HTTP (globali)

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

With OpenTelemetry SDK

Il supporto di tracciamento per i client HTTP Node.js è fornito da OpenTelemetry HTTP Instrumentation. Installa la seguente dipendenza con: npm

npm install --save @opentelemetry/instrumentation-http
      

Aggiorna la configurazione OpenTelemetry SDK come segue:

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

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

Supporto strumentale per altre librerie

Puoi trovare l'elenco completo delle strumentazioni di libreria supportate nella sezione Strumentazioni supportate OpenTelemetry JavaScript .

In alternativa, puoi cercare OpenTelemetry nel registro per scoprire se OpenTelemetry supporta la strumentazione per la tua libreria alla voce Registry.

Creazione manuale di dati di traccia

With X-Ray SDK

Utilizzando X-Ray, il codice del aws-xray-sdk pacchetto era necessario per creare manualmente i segmenti e i relativi sottosegmenti secondari per tracciare l'applicazione.

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

With OpenTelemetry SDK

È possibile creare e utilizzare intervalli personalizzati per monitorare le prestazioni delle attività interne che non vengono acquisite dalle librerie di strumentazione. Nota che solo gli intervalli di tipo Server vengono convertiti in segmenti X-Ray, tutti gli altri intervalli vengono convertiti in sottosegmenti X-Ray. Per ulteriori informazioni, consulta Segmenti.

Avrai bisogno di un'istanza Tracer dopo aver configurato l'SDK in Tracing Setup per creare Spans OpenTelemetry . È possibile creare tutte le istanze Tracer necessarie, ma è normale avere una sola istanza Tracer per un'intera applicazione.

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

Aggiungere annotazioni e metadati alle tracce con SDK OpenTelemetry

Puoi anche aggiungere coppie chiave-valore personalizzate come attributi nei tuoi span. Nota che per impostazione predefinita, tutti questi attributi span verranno convertiti in metadati nei dati grezzi di X-Ray. Per garantire che un attributo venga convertito in un'annotazione e non in metadati, aggiungete la chiave dell'attributo all'elenco dell'attributo. aws.xray.annotations Per ulteriori informazioni, vedere Abilitare le annotazioni X-Ray personalizzate.

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

Strumentazione Lambda

With X-Ray SDK

Dopo aver abilitato Active Tracing per la funzione Lambda, era necessario l'SDK X-Ray senza alcuna configurazione aggiuntiva. Lambda crea un segmento che rappresenta l'invocazione del gestore Lambda e hai creato sottosegmenti o librerie di strumenti utilizzando X-Ray SDK senza alcuna configurazione aggiuntiva.

With OpenTelemetry SDK

Puoi strumentare automaticamente la tua Lambda con livelli Lambda AWS venduti. Esistono due soluzioni:

• (Consigliato) Strato lambda di CloudWatch Application Signals

  Nota

  Questo livello Lambda dispone di CloudWatch Application Signals abilitati per impostazione predefinita, il che consente il monitoraggio delle prestazioni e dello stato dell'applicazione Lambda raccogliendo sia metriche che tracce. Se vuoi solo tracciare, devi impostare la variabile di ambiente Lambda. OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false Per ulteriori informazioni, consulta Abilita le tue applicazioni su Lambda.

• AWS layer Lambda gestito per ADOT JS. Per ulteriori informazioni, consulta AWS Distro for OpenTelemetry Lambda Support JavaScript For.

Creazione manuale di Span con strumentazione Lambda

Sebbene ADOT JavaScript Lambda Layer fornisca la strumentazione automatica per la funzione Lambda, potresti riscontrare la necessità di eseguire la strumentazione manuale nella tua Lambda, ad esempio, per fornire dati personalizzati o per il codice dello strumento all'interno della funzione Lambda stessa che non è coperto dalla strumentazione della libreria.

Per eseguire la strumentazione manuale insieme alla strumentazione automatica, è necessario aggiungerla come dipendenza. @opentelemetry/api Si consiglia che la versione di questa dipendenza sia la stessa della stessa dipendenza utilizzata da ADOT SDK. JavaScript Puoi utilizzare l' OpenTelemetry API per creare manualmente intervalli nella tua funzione Lambda.

Per aggiungere la @opentelemetry/api dipendenza usando NPM:

npm install @opentelemetry/api