Migrar para o Node.js OpenTelemetry

Quando o X-Ray SDK para Node.js foi usado, o aws-xray-sdk pacote precisou configurar o X-Ray SDK 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 que você configure 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 @opentelemetry/auto-instrumentations-node pacote:

npm install @opentelemetry/auto-instrumentations-node
        

Em seguida, atualize a configuração para habilitar todas as instrumentações da 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 ADOT para Node.js suporta:

Express.js

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

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

...

app.use(xrayExpress.closeSegment());
          

Restificar

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

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

Restificar

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 comnpm:

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 as solicitações HTTP de saída com o X-Ray, era necessário instrumentar os clientes. Por exemplo, veja 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 comnpm:

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

Usando o X-Ray, o código do aws-xray-sdk pacote foi necessário para criar manualmente segmentos e seus subsegmentos secundários para rastrear seu aplicativo.

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. Observe que somente extensões do tipo Server são convertidas em segmentos de X-Ray, todas as outras extensões são convertidas em subsegmentos de 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 do Tracer forem necessárias, mas é comum ter um Tracer para um aplicativo inteiro.

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 valores-chave personalizados como atributos em seus intervalos. Observe que, por padrão, todos esses atributos de amplitude 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();
  });
      

Depois de habilitar o Active Tracing para sua função Lambda, o X-Ray SDK foi necessário sem configuração adicional. O Lambda cria um segmento representando a invocação do manipulador Lambda, e você criou subsegmentos ou bibliotecas de instrumentos usando o X-Ray SDK sem nenhuma configuração adicional.

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

Criação manual de vãos com instrumentação 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 junto 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 @opentelemetry/api dependência usando o NPM:

npm install @opentelemetry/api