Migre a Node.js OpenTelemetry

Cuando se usó el SDK de X-Ray para Node.js, el aws-xray-sdk paquete era necesario para configurar el SDK de X-Ray con complementos de servicio o reglas de muestreo locales antes de usar el SDK para instrumentar el código.

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

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

Para el ejemplo de código que aparece a continuación, necesitará las siguientes dependencias:

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

Debe instalar y configurar el OpenTelemetry SDK antes de ejecutar el código de la aplicación. Esto se puede hacer mediante el indicador —-require. Cree un archivo denominado instrumentation.js, que contendrá la configuración y la configuración de su OpenTelemetry instrumentación.

Se recomienda configurar los siguientes componentes:

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

A continuación, puede ejecutar la aplicación con su OpenTelemetry configuración, de la siguiente manera:

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

Puedes usar las instrumentaciones de las bibliotecas del OpenTelemetry SDK para crear automáticamente intervalos para bibliotecas como el SDK. AWS Al habilitarlas, se crearán automáticamente intervalos para módulos como el SDK de la AWS versión 3. JavaScript OpenTelemetry ofrece la opción de habilitar todas las instrumentaciones de la biblioteca o especificar qué instrumentaciones de la biblioteca se deben habilitar.

Para habilitar todas las instrumentaciones, instale el paquete: @opentelemetry/auto-instrumentations-node

npm install @opentelemetry/auto-instrumentations-node
        

A continuación, actualice la configuración para habilitar todas las instrumentaciones de la biblioteca, como se muestra a continuación.

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

...

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

Puede utilizar la instrumentación automática de ADOT para Node.js OpenTelemetry para configurar automáticamente sus aplicaciones de Node.js. Al utilizar la instrumentación automática de ADOT, no es necesario realizar cambios manuales en el código para rastrear las solicitudes entrantes ni para rastrear bibliotecas como el SDK o los clientes HTTP. AWS Para obtener más información, consulte Seguimiento y métricas con la distribución para la AWS instrumentación automática. OpenTelemetry JavaScript

La instrumentación automática de ADOT para Node.js admite:

Express.js

Con el SDK de X-Ray para rastrear las solicitudes HTTP entrantes recibidas por las aplicaciones de Express.js, los dos middlewares AWSXRay.express.openSegment(<name>) y AWSXRay.express.closeSegment() eran necesarios para empaquetar todas las rutas definidas para rastrearlas.

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

...

app.use(xrayExpress.closeSegment());
          

Restify

Para rastrear las solicitudes HTTP entrantes recibidas por Restify las aplicaciones, se utilizó el middleware del SDK de X-Ray ejecutando enable desde el aws-xray-sdk-restify módulo del servidor 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

La instrumentación OpenTelemetry HTTP y la instrumentación OpenTelemetry express proporcionan soporte para Express.js el rastreo de las solicitudes entrantes. Instale las siguientes dependencias con: npm

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

Actualice la configuración del OpenTelemetry SDK para habilitar la instrumentación del módulo 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

Para las aplicaciones de Restify, necesitará la instrumentación de OpenTelemetry Restify. Instale la siguiente dependencia:

npm install --save @opentelemetry/instrumentation-restify
          

Actualice la configuración del OpenTelemetry SDK para habilitar la instrumentación del módulo restify:

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

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

Para instrumentar AWS las solicitudes salientes del AWS SDK, instrumentaste los clientes como en el siguiente ejemplo:

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 instrumentación del AWS SDK proporciona soporte para rastrear las llamadas descendentes del SDK a DynamoDB, Amazon S3 y otros. OpenTelemetry AWS Instale la siguiente dependencia con: npm

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

Actualice la configuración del OpenTelemetry SDK con la instrumentación del AWS SDK.

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

const sdk = new NodeSDK({
  ...

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

Para instrumentar las solicitudes HTTP salientes con X-Ray, era necesario instrumentar los clientes. Por ejemplo, véase más abajo.

Clientes HTTP individuales

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

Todos los clientes HTTP (globales)

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

HTTP Instrumentation proporciona soporte de rastreo para los clientes OpenTelemetry HTTP de Node.js. Instale la siguiente dependencia con: npm

npm install --save @opentelemetry/instrumentation-http
      

Actualice la configuración OpenTelemetry del SDK de la siguiente manera:

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

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

Con X-Ray, se necesitaba el código aws-xray-sdk del paquete para crear segmentos manualmente y sus subsegmentos secundarios a fin de rastrear la aplicación.

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

Puede crear y utilizar intervalos personalizados para supervisar el rendimiento de las actividades internas que no se recopilan en las bibliotecas de instrumentación. Tenga en cuenta que solo los tramos del tipo Server se convierten en segmentos de rayos X, todos los demás tramos se convierten en subsegmentos de rayos X. Para obtener más información, consulte Segmentos.

Necesitará una instancia de Tracer después de configurar el OpenTelemetry SDK en Tracing Setup para crear Spans. Puede crear tantas instancias de Tracer como necesite, pero es habitual tener una sola instancia de Tracer para toda la aplicación.

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

Añadir anotaciones y metadatos a los seguimientos con el SDK OpenTelemetry

También puedes añadir pares clave-valor personalizados como atributos en tus intervalos. Tenga en cuenta que, de forma predeterminada, todos estos atributos de intervalo se convertirán en metadatos en los datos sin procesar de X-Ray. Para garantizar que un atributo se convierta en una anotación y no en metadatos, añada la clave del atributo a la lista del aws.xray.annotations atributo. Para obtener más información, consulte Habilitar las anotaciones de rayos X personalizadas.

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

Tras habilitar Active Tracing para la función Lambda, se necesitaba el SDK de X-Ray sin necesidad de configuración adicional. Lambda crea un segmento que representa la invocación del controlador de Lambda y usted creó subsegmentos o bibliotecas de instrumentos mediante el SDK de X-Ray sin ninguna configuración adicional.

Puede instrumentar automáticamente su Lambda con capas Lambda AWS vendidas. Hay dos soluciones:

Creación manual de tramos con instrumentación Lambda

Si bien la capa JavaScript Lambda de ADOT proporciona instrumentación automática para la función Lambda, es posible que necesite realizar una instrumentación manual en la Lambda, por ejemplo, para proporcionar datos personalizados o para instrumentar código dentro de la propia función Lambda que no está cubierto por las instrumentaciones de la biblioteca.

Para realizar la instrumentación manual junto con la instrumentación automática, tendrá que añadirla como dependencia. @opentelemetry/api Se recomienda que la versión de esta dependencia sea la misma versión de la misma dependencia que utiliza el SDK de JavaScript ADOT. Puede usar la OpenTelemetry API para crear intervalos manualmente en la función Lambda.

Para añadir la @opentelemetry/api dependencia mediante NPM:

npm install @opentelemetry/api