Migrar para Node.js OpenTelemetry

Quando o SDK do X-Ray para Node.js foi usado, o pacote aws-xray-sdk precisou configurar o SDK do X-Ray com plug-ins de serviço ou regras de amostragem locais antes de usar o SDK para instrumentar seu código.

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

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

Para o exemplo de código abaixo, você precisará das seguintes dependências:

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

Você deve instalar e configurar o OpenTelemetry SDK antes de executar o código do aplicativo. Isso pode ser feito usando o sinalizador –-require. Crie um arquivo chamado instrumentation.js, que conterá sua configuração e configuração OpenTelemetry de instrumentação.

É recomendável configurar os seguintes 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();
        

Em seguida, você pode executar seu aplicativo com sua OpenTelemetry configuração, como:

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

Você pode usar as instrumentações da biblioteca do OpenTelemetry SDK para criar automaticamente extensões para bibliotecas como o SDK. AWS Habilitá-los criará automaticamente extensões para módulos, como o AWS SDK para JavaScript v3. OpenTelemetry fornece a opção de ativar todas as instrumentações da biblioteca ou especificar quais instrumentações da biblioteca devem ser ativadas.

Para habilitar todas as instrumentações, instale o pacote @opentelemetry/auto-instrumentations-node:

npm install @opentelemetry/auto-instrumentations-node
        

Em seguida, atualize a configuração para habilitar todas as instrumentações de biblioteca, conforme mostrado abaixo.

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

...

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

Você pode usar a instrumentação automática ADOT para Node.js OpenTelemetry para configurar automaticamente seus aplicativos Node.js. Ao usar o ADOT Auto-Instrumentation, você não precisa fazer alterações manuais no código para rastrear solicitações recebidas ou rastrear bibliotecas, como os AWS clientes SDK ou HTTP. Para obter mais informações, consulte Rastreamento e métricas com a AWS distribuição para OpenTelemetry JavaScript instrumentação automática.

A instrumentação automática do ADOT para Node.js é compatível com:

Express.js

Com o SDK do X-Ray para rastrear solicitações HTTP recebidas pelas aplicações Express.js, os dois middlewares AWSXRay.express.openSegment(<name>) e AWSXRay.express.closeSegment() precisavam agrupar todas as rotas definidas para rastreá-las.

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

...

app.use(xrayExpress.closeSegment());
          

Restify

Para rastrear as solicitações HTTP recebidas pelas aplicações Restify, o middleware do SDK do X-Ray foi usado executando enable no módulo aws-xray-sdk-restify no 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

O suporte de rastreamento para solicitações recebidas Express.js é fornecido pela instrumentação OpenTelemetry HTTP e pela instrumentação expressa. OpenTelemetry Instale as seguintes dependências com npm:

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

Atualize a configuração do OpenTelemetry SDK para habilitar a instrumentação para o módulo expresso:

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 aplicativos Restify, você precisará da instrumentação OpenTelemetry Restify. Instale a seguinte dependência:

npm install --save @opentelemetry/instrumentation-restify
          

Atualize a configuração do OpenTelemetry SDK para habilitar a instrumentação para o módulo restify:

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

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

Para instrumentar as AWS solicitações de saída do AWS SDK, você instrumentou clientes como no exemplo a seguir:

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

O suporte de rastreamento para chamadas downstream do AWS SDK para o DynamoDB, o Amazon S3 e outros é fornecido pela instrumentação do SDK. OpenTelemetry AWS Instale a seguinte dependência com npm:

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

Atualize a configuração do OpenTelemetry SDK com a instrumentação do AWS SDK.

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

const sdk = new NodeSDK({
  ...

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

Para instrumentar solicitações HTTP de saída com o X-Ray, era necessário instrumentar os clientes. Confira um exemplo abaixo.

Clientes HTTP individuais

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

Todos os clientes HTTP (globais)

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

O suporte de rastreamento para clientes HTTP Node.js é fornecido pela Instrumentação OpenTelemetry HTTP. Instale a seguinte dependência com npm:

npm install --save @opentelemetry/instrumentation-http
      

Atualize a configuração do OpenTelemetry SDK da seguinte forma:

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

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

Ao usar o X-Ray, o código do pacote aws-xray-sdk era necessário para criar manualmente segmentos e seus subsegmentos filho para rastrear sua aplicação.

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

Você pode criar e usar extensões personalizadas para monitorar o desempenho de atividades internas que não são capturadas pelas bibliotecas de instrumentação. Somente extensões do tipo servidor são convertidas em segmentos do X-Ray. Todas as outras extensões são convertidas em subsegmentos do X-Ray. Para mais informações, leia Segmentos.

Você precisará de uma instância do Tracer depois de configurar o OpenTelemetry SDK na Configuração de rastreamento para criar Spans. Você pode criar quantas instâncias de rastreador forem necessárias, mas é comum ter um rastreador para toda a aplicação.

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

Adicionar anotações e metadados aos rastreamentos com o SDK OpenTelemetry

Você também pode adicionar pares de valor-chave personalizados como atributos nas extensões. Por padrão, todos esses atributos de extensão serão convertidos em metadados nos dados brutos do X-Ray. Para garantir que um atributo seja convertido em uma anotação, e não em metadados, adicione a chave do atributo à lista do atributo aws.xray.annotations. Para obter mais informações, consulte 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();
  });
      

Após a habilitação do Rastreamento ativo para sua função do Lambda, o SDK do X-Ray será necessário sem configuração adicional. O Lambda cria um segmento representando a invocação do manipulador do Lambda, e você cria subsegmentos ou bibliotecas de instrumentos usando o SDK do X-Ray sem nenhuma configuração adicional.

Você pode instrumentar automaticamente seu Lambda com camadas personalizadas do AWS Lambda. Existem duas soluções:

Criar manualmente extensões com instrumentação do Lambda

Embora o ADOT JavaScript Lambda Layer forneça instrumentação automática para sua função Lambda, você pode achar necessário realizar instrumentação manual em seu Lambda, por exemplo, para fornecer dados personalizados ou instrumentar código dentro da própria função Lambda que não seja coberto pelas instrumentações da biblioteca.

Para realizar a instrumentação manual com a instrumentação automática, você precisará adicionar @opentelemetry/api como uma dependência. Recomenda-se que a versão dessa dependência seja a mesma versão da mesma dependência usada pelo SDK JavaScript ADOT. Você pode usar a OpenTelemetry API para criar extensões manualmente em sua função Lambda.

Para adicionar a dependência @opentelemetry/api usando o NPM:

npm install @opentelemetry/api