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á. # Configurar o X-Ray SDK para Node.js **nota** Aviso de SDK/Daemon manutenção do X-Ray — Em 25 de fevereiro de 2026, o AWS X-Ray SDKs/Daemon entrará no modo de manutenção, onde AWS limitará as versões do X-Ray SDK e do Daemon para tratar apenas de problemas de segurança. Para obter mais informações sobre a linha do tempo do suporte, consulte [Cronograma de suporte do X-Ray SDK e do Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar para o. OpenTelemetry Para obter mais informações sobre a migração para OpenTelemetry, consulte [Migrando da instrumentação X-Ray para a instrumentação](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry Você pode configurar o X-Ray SDK para Node.js com plug-ins para incluir informações sobre o serviço em que a aplicação é executada, modificar o comportamento de amostragem padrão ou adicionar regras de amostragem que se aplicam a solicitações para caminhos específicos. **Topics** + [Plug-ins de serviço](#xray-sdk-nodejs-configuration-plugins) + [Regras de amostragem](#xray-sdk-nodejs-configuration-sampling) + [Registro em log](#xray-sdk-nodejs-configuration-logging) + [Endereço do daemon do X-Ray](#xray-sdk-nodejs-configuration-daemon) + [Variáveis de ambiente](#xray-sdk-nodejs-configuration-envvars) ## Plug-ins de serviço Use `plugins` para registrar informações sobre o serviço que hospeda o aplicativo. **Plugins** + Amazon EC2 — `EC2Plugin` adiciona o ID da instância, a zona de disponibilidade e o grupo de CloudWatch registros. + Elastic Beanstalk: o `ElasticBeanstalkPlugin` adiciona o nome do ambiente, o rótulo da versão e o ID de implantação. + Amazon ECS: o `ECSPlugin` adiciona o ID do contêiner. Para usar um plug-in, configure o cliente do X-Ray SDK para Node.js usando o método `config`. **Example app.js – plug-ins** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.config([AWSXRay.plugins.EC2Plugin,AWSXRay.plugins.ElasticBeanstalkPlugin]); ``` O SDK também usa as configurações do plug-in para definir o campo `origin` no segmento. Isso indica o tipo de AWS recurso que executa seu aplicativo. Quando você usa vários plug-ins, o SDK usa a seguinte ordem de resolução para determinar a origem: ElasticBeanstalk > EKS > ECS >. EC2 ## Regras de amostragem O SDK usa as regras de amostragem que você define no console do X-Ray para determinar quais solicitações serão registradas. A regra padrão rastreia a primeira solicitação a cada segundo e 5% de todas as solicitações adicionais em todos os serviços que enviam rastreamentos ao X-Ray. [Crie regras adicionais no console do X-Ray](xray-console-sampling.md) para personalizar a quantidade de dados registrados para cada uma dos aplicativos. O SDK aplica regras personalizadas na ordem em que elas estão definidas. Se uma solicitação corresponder a várias regras personalizadas, o SDK aplicará somente a primeira regra. **nota** Se o SDK não conseguir acessar o X-Ray para obter regras de amostragem, ele reverterá para uma regra local padrão da primeira solicitação a cada segundo e 5% de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar a amostragem APIs ou não conseguir se conectar ao daemon X-Ray, que atua como um proxy TCP para chamadas de API feitas pelo SDK. Você também pode configurar o SDK para carregar regras de amostragem de um documento JSON. O SDK pode usar regras locais como backup para casos em que a amostragem do X-Ray não está disponível ou usar exclusivamente regras locais. **Example sampling-rules.json** ``` { "version": 2, "rules": [ { "description": "Player moves.", "host": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` Este exemplo define uma regra personalizada e uma regra padrão. A regra personalizada aplica uma taxa de amostragem de 5% sem um número mínimo de solicitações para rastrear os caminhos em `/api/move/`. A regra padrão rastreia a primeira solicitação a cada segundo e 10% das solicitações adicionais. A desvantagem de definir regras localmente é que o destino fixo é aplicado por instância do gravador de forma independente, em vez de ser gerenciado pelo serviço X-Ray. À medida que você implanta mais hosts, a taxa fixa é multiplicada, dificultando o controle da quantidade de dados registrados. Ativado AWS Lambda, você não pode modificar a taxa de amostragem. Se sua função for chamada por um serviço instrumentado, as chamadas que geraram solicitações que foram amostradas por esse serviço serão registradas pelo Lambda. Se o rastreamento ativo estiver habilitado e nenhum cabeçalho de rastreamento estiver presente, o Lambda tomará a decisão de amostragem. Para configurar regras de backup, instrua o X-Ray SDK para Node.js a carregar regras de amostragem de um arquivo com `setSamplingRules`. **Example app.js – regras de amostragem de um arquivo** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.middleware.setSamplingRules('sampling-rules.json'); ``` Você também pode definir suas regras em código e transmiti-los a `setSamplingRules` como um objeto. **Example app.js – regras de amostra de um arquivo** ``` var AWSXRay = require('aws-xray-sdk'); var rules = { "rules": [ { "description": "Player moves.", "service_name": "*", "http_method": "*", "url_path": "/api/move/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 }, "version": 1 } AWSXRay.middleware.setSamplingRules(rules); ``` Para usar apenas regras locais, chame `disableCentralizedSampling`. ``` AWSXRay.middleware.disableCentralizedSampling() ``` ## Registro em log Para registrar a saída do SDK, chame `AWSXRay.setLogger(logger)`, em que `logger` é um objeto que fornece métodos de registro padrão (`warn`, `info` etc.). Por padrão, o SDK registrará as mensagens de erro em log no console usando os métodos padrão no objeto do console. O nível de log do registrador integrado pode ser definido usando as variáveis de ambiente `AWS_XRAY_DEBUG_MODE` ou `AWS_XRAY_LOG_LEVEL`. Para obter uma lista de valores de nível de log válidos, consulte [Variáveis de ambiente](#xray-sdk-nodejs-configuration-envvars). Se quiser fornecer um formato ou destino diferente para os logs, você pode fornecer ao SDK sua própria implementação da interface do registrador, conforme mostrado abaixo. Qualquer objeto que implemente essa interface pode ser usado. Isso significa que muitas bibliotecas de registro em log (por exemplo, Winston) podem ser usadas e passadas diretamente para o SDK. **Example app.js – registro** ``` var AWSXRay = require('aws-xray-sdk'); // Create your own logger, or instantiate one using a library. var logger = { error: (message, meta) => { /* logging code */ }, warn: (message, meta) => { /* logging code */ }, info: (message, meta) => { /* logging code */ }, debug: (message, meta) => { /* logging code */ } } AWSXRay.setLogger(logger); AWSXRay.config([AWSXRay.plugins.EC2Plugin]); ``` Chame `setLogger` antes de executar outros métodos de configuração para garantir que você capture a saída dessas operações. ## Endereço do daemon do X-Ray Se o daemon do X-Ray escuta em uma porta ou host diferente de `127.0.0.1:2000`, você pode configurar o X-Ray SDK para Node.js para enviar dados de rastreamento a um endereço diferente. ``` AWSXRay.setDaemonAddress('host:port'); ``` Você pode especificar o host por nome ou IPv4 endereço. **Example app.js – endereço daemon** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('daemonhost:8082'); ``` Se você tiver configurado o daemon para escutar em portas diferentes para TCP e UDP, poderá especificar ambas na configuração de endereço do daemon. **Example app.js – endereço daemon em portas separadas** ``` var AWSXRay = require('aws-xray-sdk'); AWSXRay.setDaemonAddress('tcp:daemonhost:8082 udp:daemonhost:8083'); ``` Você também pode definir o endereço daemon usando a `AWS_XRAY_DAEMON_ADDRESS` [variável de ambiente](#xray-sdk-nodejs-configuration-envvars). ## Variáveis de ambiente Você pode usar variáveis de ambiente para configurar o X-Ray SDK para Node.js. O SDK é compatível com as variáveis a seguir. + `AWS_XRAY_CONTEXT_MISSING`: defina como `RUNTIME_ERROR` para lançar exceções, caso o código instrumentado tente registrar dados quando nenhum segmento estiver aberto. **Valores válidos** + `RUNTIME_ERROR`: lance uma exceção de tempo de execução. + `LOG_ERROR`: registre um erro e continue (padrão). + `IGNORE_ERROR`: ignore o erro e continue. Erros relativos a segmentos ou subsegmentos ausentes poderão ocorrer quando você tentar usar um cliente instrumentado no código de inicialização que é executado quando nenhuma solicitação estiver aberta ou em um código que gere um novo thread. + `AWS_XRAY_DAEMON_ADDRESS`: defina o host e a porta do receptor do daemon do X-Ray. Por padrão, o SDK usa `127.0.0.1:2000` para dados de rastreamento (UDP) e para amostragem (TCP). Use essa variável se você tiver configurado o daemon para [escutar em uma porta diferente](xray-daemon-configuration.md) ou se ele estiver sendo executado em um host diferente. **Formato** + **Mesma porta**: `address:port` + **Portas diferentes**: `tcp:address:port udp:address:port` + `AWS_XRAY_DEBUG_MODE`: defina como `TRUE` para configurar o SDK para enviar logs ao console, em nível de `debug`. + `AWS_XRAY_LOG_LEVEL `: defina um nível de log para o registrador padrão. Os valores válidos são `debug`, `info`, `warn`, `error` e `silent`. Esse valor é ignorado quando AWS\$1XRAY\$1DEBUG\$1MODE definido como`TRUE`. + `AWS_XRAY_TRACING_NAME`: defina um nome de serviço para o SDK usar para segmentos. Sobrepõe o nome do segmento que você [definiu no middleware Express](xray-sdk-nodejs-middleware.md).