As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Migrar para Node.js OpenTelemetry Esta seção explica como migrar seus aplicativos Node.js do X-Ray SDK para o. OpenTelemetry Ela abrange abordagens de instrumentação automática e manual e fornece exemplos específicos para casos de uso comuns. O SDK X-Ray Node.js ajuda você a instrumentar manualmente suas aplicações Node.js para rastreamento. Esta seção fornece exemplos de código para migrar do X-Ray para a OpenTelemetry instrumentação. **Topics** + [Soluções de instrumentação automática de código zero](#zero-code-instrumentation) + [Soluções de instrumentação manual](#manual-instrumentation) + [Rastreamento de solicitações de entrada](#tracing-incoming-requests) + [AWS Instrumentação do SDK JavaScript V3](#aws-sdk-instrumentation) + [Instrumentar chamadas HTTP de saída](#http-instrumentation) + [Suporte de instrumentação para outras bibliotecas](#other-libraries) + [Criar dados de rastreamento manualmente](#manual-trace-creation) + [Instrumentação do Lambda](#lambda-instrumentation) ## Soluções de instrumentação automática de código zero Para rastrear solicitações com o SDK do X-Ray para Node.js, você deve modificar o código da aplicação. Com OpenTelemetry, você pode usar soluções de instrumentação automática de código zero para rastrear solicitações. **Instrumentação automática de código zero com instrumentações automáticas OpenTelemetry baseadas.** 1. Usando a AWS distro para instrumentação automática OpenTelemetry (ADOT) para Node.js — Para instrumentação automática para o aplicativo Node.js, consulte [Rastreamento e métricas com a distribuição para instrumentação](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr) automática. AWS OpenTelemetry JavaScript (Opcional) Você também pode ativar o CloudWatch Application Signals ao instrumentar automaticamente seus aplicativos AWS com a JavaScript instrumentação automática ADOT para monitorar a integridade atual do aplicativo e acompanhar o desempenho de longo prazo do aplicativo em relação aos seus objetivos de negócios. O Application Signals fornece uma visualização unificada e centrada em aplicativos para aplicativos, serviços e dependências, além de ajudar você a monitorar e realizar a triagem da integridade do aplicativo. Para obter mais informações, consulte [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html). 1. [Usando a instrumentação automática de OpenTelemetry JavaScript código zero — Para instrumentação automática com o, consulte instrumentação de código zero. OpenTelemetry JavaScript JavaScript ](https://opentelemetry.io/docs/zero-code/js/) ## Soluções de instrumentação manual ------ #### [ Tracing setup with X-Ray SDK ] 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(); ``` ------ #### [ Tracing setup with OpenTelemetry SDK ] **nota** AWS No momento, o X-Ray Remote Sampling não está disponível para ser configurado para OpenTelemetry JS. No entanto, o suporte para a amostragem remota do X-Ray está atualmente disponível por meio da instrumentação automática do ADOT para Node.js. 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](https://nodejs.org/api/cli.html#-r---require-module). Crie um arquivo chamado *instrumentation.js*, que conterá sua configuração e configuração OpenTelemetry de instrumentação. É recomendável configurar os seguintes componentes: + OTLPTraceExportador — Obrigatório para exportar traços para o Agente/Coletor CloudWatch OpenTelemetry + AWSXRayPropagator — Necessário para propagar o Trace Context para AWS serviços integrados ao X-Ray + Detectores de recursos (por exemplo, detector de recursos do Amazon EC2): para detectar metadados do host que executa sua aplicação ``` /*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 }); ``` ------ #### [ Tracing setup with ADOT auto-instrumentation for Node.js ] 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 ](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr) instrumentação automática. A instrumentação automática do ADOT para Node.js é compatível com: + Amostragem remota do X-Ray por meio de variável de ambiente: `export OTEL_TRACES_SAMPLER=xray` + Propagação do contexto de rastreamento do X-Ray (habilitada por padrão) + Detecção de recursos (a detecção de recursos para ambientes Amazon EC2, Amazon ECS e Amazon EKS é habilitada por padrão) + Instrumentações de biblioteca automática para todas as OpenTelemetry instrumentações suportadas, que podem ser disabled/enabled seletivamente por meio de variáveis de ambiente `OTEL_NODE_ENABLED_INSTRUMENTATIONS` `OTEL_NODE_DISABLED_INSTRUMENTATIONS` + Criação manual de expansões ------ ## Rastreamento de solicitações de entrada ------ #### [ With X-Ray SDK ] **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()` 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')); ``` ------ #### [ With OpenTelemetry SDK ] **Express.js** [O suporte de rastreamento para solicitações recebidas `Express.js` é fornecido pela [instrumentação OpenTelemetry HTTP e pela instrumentação expressa.](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http) OpenTelemetry ](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express) 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](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-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(), ], }); ``` ------ ## AWS Instrumentação do SDK JavaScript V3 ------ #### [ With X-Ray SDK ] 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!', })); ``` ------ #### [ With OpenTelemetry SDK ] 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() ], }); ``` ------ ## Instrumentar chamadas HTTP de saída ------ #### [ With X-Ray SDK ] 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'); ``` ------ #### [ With OpenTelemetry SDK ] 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(), ], }); ``` ------ ## Suporte de instrumentação para outras bibliotecas Você pode encontrar a lista completa de instrumentações de biblioteca suportadas OpenTelemetry JavaScript em Instrumentações [suportadas](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/metapackages/auto-instrumentations-node#supported-instrumentations). [Como alternativa, você pode pesquisar no OpenTelemetry registro para descobrir se OpenTelemetry oferece suporte à instrumentação para sua biblioteca em Registro.](https://opentelemetry.io/ecosystem/registry/) ## Criar dados de rastreamento manualmente ------ #### [ With X-Ray SDK ] 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(); ``` ------ #### [ With OpenTelemetry SDK ] 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-segments). 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](https://aws-otel.github.io/docs/getting-started/x-ray#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(); }); ``` ------ ## Instrumentação do Lambda ------ #### [ With X-Ray SDK ] 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. ------ #### [ With OpenTelemetry SDK ] Você pode instrumentar automaticamente seu Lambda com camadas personalizadas do AWS Lambda. Existem duas soluções: + (Recomendado) AWS Lambda Layer para OpenTelemetry **nota** Essa camada Lambda tem sinais de CloudWatch aplicativo ativados por padrão, o que permite o monitoramento de desempenho e integridade de seu aplicativo Lambda por meio da coleta de métricas e rastreamentos. Se você quiser somente o rastreamento, defina a variável de ambiente `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` do Lambda. Para obter mais informações, consulte [Habilitar aplicações no Lambda](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html). + AWS camada Lambda gerenciada para ADOT JS. Para obter mais informações, consulte [AWS Distro for OpenTelemetry Lambda Support JavaScript For](https://aws-otel.github.io/docs/getting-started/lambda/lambda-js). **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 ``` ------