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á.
# Trabalho com 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
Há duas maneiras de instrumentar um aplicativo Node.js para enviar rastreamentos ao X-Ray:
+ [AWS Distro for OpenTelemetry JavaScript](xray-js-opentel-sdk.md) — Uma AWS distribuição que fornece um conjunto de bibliotecas de código aberto para enviar métricas e rastreamentos correlacionados para várias soluções de AWS monitoramento, incluindo Amazon e Amazon OpenSearch Service CloudWatch AWS X-Ray, por meio do [AWS Distro](https://aws-otel.github.io/docs/getting-started/collector) for Collector. OpenTelemetry
+ [AWS X-Ray SDK para Node.js](xray-sdk-nodejs.md) — Um conjunto de bibliotecas para gerar e enviar rastreamentos para o X-Ray por meio do [daemon X-Ray](xray-daemon.md).
Para obter mais informações, consulte [Escolhendo entre o AWS Distro for OpenTelemetry e o X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing).
# AWS Distro para OpenTelemetry JavaScript
Com o AWS Distro para OpenTelemetry (ADOT) JavaScript, você pode instrumentar as aplicações uma vez e enviar métricas e rastreamentos correlacionados para várias soluções de monitoramento da AWS como o Amazon CloudWatch, o AWS X-Ray e o Amazon OpenSearch Service. O uso do X-Ray com o AWS Distro para OpenTelemetry requer dois componentes: um *SDK do OpenTelemetry* habilitado para uso com o X-Ray e o *coletor AWS Distro para OpenTelemetry* habilitado para uso com o X-Ray.
Para começar, consulte a documentação do [AWS Distro para OpenTelemetry JavaScript](https://aws-otel.github.io/docs/getting-started/javascript-sdk).
**nota**
O ADOT JavaScript é compatível com todos as aplicações Node.js do lado do servidor. O ADOT JavaScript não consegue exportar dados para o X-Ray por meio de clientes de navegador.
Para obter mais informações sobre como usar o AWS Distro para OpenTelemetry com o AWS X-Ray e outros Serviços da AWS, consulte [AWS Distro para OpenTelemetry](https://aws-otel.github.io/) ou a [documentação do AWS Distro para OpenTelemetry](https://aws-otel.github.io/docs/introduction).
Para obter mais informações sobre compatibilidade de idiomas e uso, consulte [AWSobservability no GitHub](https://github.com/aws-observability).
# AWS 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
O X-Ray SDK para Node.js é uma biblioteca para aplicações web Express e funções do Lambda em Node.js que fornece classes e métodos para gerar e enviar dados de rastreamento ao daemon do X-Ray. Os dados de rastreamento incluem informações sobre solicitações HTTP recebidas pelo aplicativo e chamadas que o aplicativo faz para serviços downstream usando o AWS SDK ou clientes HTTP.
**nota**
O SDK do X-Ray para Node.js é um projeto de código aberto que é compatível com Node.js nas versões 14.x e superiores. Você pode acompanhar o projeto e enviar problemas e pull requests em GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-node)- xray-sdk-node
Se você usa o Express, comece [adicionando o SDK como middleware](xray-sdk-nodejs-middleware.md) em seu servidor de aplicativo para rastrear solicitações recebidas. O middleware cria um [segmento](xray-concepts.md#xray-concepts-segments) para cada solicitação rastreada e conclui o segmento quando a resposta é enviada. Embora o segmento esteja aberto, você pode usar os métodos do cliente do SDK para adicionar informações ao segmento e criar subsegmentos para rastrear as chamadas subsequentes. O SDK também registra automaticamente exceções que seu aplicativo lança enquanto o segmento está aberto.
Para funções do Lambda chamadas por um aplicativo ou um serviço instrumentado, o Lambda lê o [cabeçalho de rastreamento](xray-concepts.md#xray-concepts-tracingheader) e rastreia automaticamente as solicitações amostradas. Para outras funções, você pode [configurar o Lambda](xray-services-lambda.md) para amostrar e rastrear solicitações recebidas. Em ambos os casos, o Lambda cria o segmento e o fornece ao X-Ray SDK.
**nota**
No Lambda, o X-Ray SDK é opcional. Se você não o usar em sua função, mesmo assim o mapa de serviço incluirá um nó para o serviço Lambda e um para cada função do Lambda. Ao adicionar o SDK, você pode instrumentar o código da função para adicionar subsegmentos ao segmento de função registrado pelo Lambda. Consulte [AWS Lambda and AWS X-Ray](xray-services-lambda.md) para obter mais informações.
Em seguida, use o X-Ray SDK para Node.js para [instrumentar seu AWS SDK JavaScript em clientes Node.js](xray-sdk-nodejs-awssdkclients.md). Sempre que você faz uma chamada para um downstream AWS service (Serviço da AWS) ou recurso com um cliente instrumentado, o SDK registra as informações sobre a chamada em um subsegmento. Serviços da AWS e os recursos que você acessa nos serviços aparecem como nós downstream no mapa de rastreamento para ajudá-lo a identificar erros e problemas de limitação em conexões individuais.
O X-Ray SDK para Node.js também fornece instrumentação para chamadas downstream para consultas HTTP Web APIs e SQL. [Encapsule seu cliente HTTP no método de captura do SDK](xray-sdk-nodejs-httpclients.md) para registrar informações sobre chamadas HTTP de saída. Para clientes SQL, [use o método de captura para o seu tipo de banco de dados](xray-sdk-nodejs-sqlclients.md).
O middleware aplica regras de amostragem a solicitações recebidas para determinar quais solicitações devem ser rastreadas. Você pode [configurar o X-Ray SDK para Node.js para](xray-sdk-nodejs-configuration.md) ajustar o comportamento de amostragem ou registrar informações sobre os recursos AWS computacionais nos quais seu aplicativo é executado.
Registre informações adicionais sobre as solicitações e o trabalho que o aplicativo faz em [anotações e metadados](xray-sdk-nodejs-segment.md). Anotações são simples pares de chave-valor que são indexados para serem usados com [expressões de filtro](xray-console-filters.md) para que você possa pesquisar rastreamentos que contêm dados específicos. As entradas de metadados são menos restritivas e podem registrar matrizes e objetos inteiros: tudo o que pode ser serializado em JSON.
**Anotações e metadados**
Anotações e metadados são textos arbitrários que você adiciona aos segmentos com o X-Ray SDK. As anotações são indexadas para serem usadas com expressões de filtro. Os metadados não são indexados, mas podem ser visualizados no segmento bruto com o console ou a API do X-Ray. Qualquer pessoa à qual você conceder acesso de leitura ao X-Ray poderá visualizar esses dados.
Quando há uma grande quantidade de clientes instrumentados no código, um único segmento de solicitação pode conter um grande número de subsegmentos, um para cada chamada feita com um cliente instrumentado. Você pode organizar e agrupar subsegmentos integrando chamadas de clientes em [subsegmentos personalizados](xray-sdk-nodejs-subsegments.md). Você pode criar um subsegmento personalizado para uma função inteira ou qualquer seção de código e registrar metadados e anotações no subsegmento em vez de gravar tudo no segmento principal.
Para documentação de referência sobre as classes e os métodos do SDK, consulte a [Referência de API do AWS X-Ray SDK para Node.js](https://docs.aws.amazon.com//xray-sdk-for-nodejs/latest/reference).
## Requisitos
O X-Ray SDK para Node.js requer o Node.js e as seguintes bibliotecas:
+ `atomic-batcher`: 1.0.2
+ `cls-hooked`: 4.2.2
+ `pkginfo`: 0.4.0
+ `semver`: 5.3.0
O SDK obtém essas bibliotecas quando você o instala com NPM.
Para rastrear clientes AWS SDK, o X-Ray SDK para Node.js exige uma versão mínima do AWS SDK para JavaScript Node.js.
+ `aws-sdk`: 2.7.15
## Gerenciamento de dependências
O X-Ray SDK para Node.js está disponível no NPM.
+ **Pacote**: [https://www.npmjs.com/package/aws-xray-sdk](https://www.npmjs.com/package/aws-xray-sdk)
Para desenvolvimento local, instale o SDK no diretório de projetos com npm.
```
~/nodejs-xray$ npm install aws-xray-sdk
aws-xray-sdk@3.3.3
├─┬ aws-xray-sdk-core@3.3.3
│ ├── @aws-sdk/service-error-classification@3.15.0
│ ├── @aws-sdk/types@3.15.0
│ ├─┬ @types/cls-hooked@4.3.3
│ │ └── @types/node@15.3.0
│ ├── atomic-batcher@1.0.2
│ ├─┬ cls-hooked@4.2.2
│ │ ├─┬ async-hook-jl@1.7.6
│ │ │ └── stack-chain@1.3.7
│ │ └─┬ emitter-listener@1.1.2
│ │ └── shimmer@1.2.1
│ └── semver@5.7.1
├── aws-xray-sdk-express@3.3.3
├── aws-xray-sdk-mysql@3.3.3
└── aws-xray-sdk-postgres@3.3.3
```
Use a opção `--save` para salvar o SDK como uma dependência no `package.json` no seu aplicativo.
```
~/nodejs-xray$ npm install aws-xray-sdk --save
aws-xray-sdk@3.3.3
```
Se a aplicação tiver alguma dependência cujas versões entrem em conflito com as dependências do X-Ray SDK, ambas as versões serão instaladas para garantir a compatibilidade. Para obter mais detalhes, consulte a [documentação oficial do NPM para resolução de dependências](http://npm.github.io/how-npm-works-docs/npm3/how-npm3-works.html).
## Amostras de Node.js
Trabalhe com o AWS X-Ray SDK para Node.js para ter uma end-to-end visão das solicitações à medida que elas percorrem seus aplicativos Node.js.
+ [Aplicação de amostra Node.js](https://github.com/aws-samples/aws-xray-sdk-node-sample) ativada GitHub.
# 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).
# Rastrear solicitações de entrada com 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 usar o X-Ray SDK para Node.js para rastrear solicitações HTTP recebidas que seus aplicativos Express e Restify atendem em uma instância do EC2 no Amazon EC2 ou no Amazon ECS. AWS Elastic Beanstalk
O X-Ray SDK para Node.js fornece middleware para aplicações que usam os frameworks Express e Restify. Quando você adiciona o middleware do X-Ray ao aplicativo, o X-Ray SDK para Node.js cria um segmento para cada solicitação amostrada. Este segmento inclui tempo, método e disposição da solicitação HTTP. Instrumentação adicional cria subsegmentos sobre esse segmento.
**nota**
Para AWS Lambda funções, o Lambda cria um segmento para cada solicitação de amostra. Consulte [AWS Lambda and AWS X-Ray](xray-services-lambda.md) para obter mais informações.
Cada segmento tem um nome que identifica o aplicativo no mapa de serviços. O segmento pode ser nomeado estaticamente ou você pode configurar o SDK para nomeá-lo dinamicamente com base no cabeçalho do host na solicitação de entrada. A nomeação dinâmica permite agrupar rastreamentos com base no nome de domínio na solicitação e aplicar um nome padrão se o nome não corresponder ao padrão esperado (por exemplo, se o cabeçalho do host for falsificado).
**Solicitações encaminhadas**
Se um balanceador de carga ou outro intermediário encaminhar uma solicitação para o aplicativo, o X-Ray obterá o IP do cliente do cabeçalho `X-Forwarded-For` na solicitação em vez do IP de origem no pacote IP. O IP do cliente registrado para uma solicitação encaminhada pode ser falsificado; portanto, não é digno de confiança.
Quando uma solicitação é encaminhada, o SDK define um campo adicional no segmento para indicar isso. Se o segmento tiver o campo `x_forwarded_for` definido como `true`, isso significa que o IP do cliente foi obtido no cabeçalho `X-Forwarded-For` na solicitação HTTP.
O manipulador de mensagens cria um segmento para cada solicitação recebida com um bloco `http` que contém as seguintes informações:
+ **Método HTTP**: GET, POST, PUT, DELETE etc.
+ **Endereço do cliente**: o endereço IP do cliente que enviou a solicitação.
+ **Código de resposta**: o código de resposta HTTP da solicitação concluída.
+ **Horário**: a hora de início (quando a solicitação foi recebida) e a hora de término (quando a resposta foi enviada).
+ **Agente do usuário**: o `user-agent` da solicitação.
+ **Tamanho do conteúdo**: o `content-length` da resposta.
**Topics**
+ [Rastreamento de solicitações recebidas com Express](#xray-sdk-nodejs-middleware-express)
+ [Rastreamento de solicitações recebidas com Restify](#xray-sdk-nodejs-middleware-restify)
+ [Configurar uma estratégia de nomeação de segmentos](#xray-sdk-nodejs-middleware-naming)
## Rastreamento de solicitações recebidas com Express
Para usar o middleware Express, inicie o cliente do SDK e use o middleware retornado pela função `express.openSegment` antes de definir as rotas.
**Example app.js – Express**
```
var app = express();
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment());
```
Depois de definir as rotas, use a saída de `express.closeSegment`, como mostrado, para lidar com quaisquer erros retornados pelo X-Ray SDK para Node.js.
## Rastreamento de solicitações recebidas com Restify
Para usar o middleware Restify, inicie o cliente do SDK e execute `enable`. Transmita seu servidor Restify e o nome do segmento.
**Example app.js – 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'));
server.get('/', function (req, res) {
res.render('index');
});
```
## Configurar uma estratégia de nomeação de segmentos
AWS X-Ray usa um *nome de serviço* para identificar seu aplicativo e diferenciá-lo dos outros aplicativos, bancos de dados APIs, AWS recursos externos e que seu aplicativo usa. Quando o X-Ray SDK gera segmentos para solicitações recebidas, ele registra o nome do serviço do aplicativo no [campo de nome](xray-api-segmentdocuments.md#api-segmentdocuments-fields) do segmento.
O X-Ray SDK pode nomear segmentos com o nome do host no cabeçalho da solicitação HTTP. No entanto, esse cabeçalho pode ser falsificado, o que pode resultar em nós inesperados no mapa de serviço. Para evitar que o SDK nomeie segmentos incorretamente devido a solicitações com cabeçalhos de host falsificados, você deve especificar um nome padrão para as solicitações recebidas.
Se o aplicativo atende a solicitações para vários domínios, você pode configurar o SDK para usar uma estratégia de nomeação dinâmica para refletir isso nos nomes dos segmentos. Uma estratégia de nomeação dinâmica permite que o SDK use o nome do host para solicitações que correspondam a um padrão esperado e aplique o nome padrão às solicitações que não correspondem.
Por exemplo, você pode ter uma único aplicativo para atender a solicitações para três subdomínios: `www.example.com`, `api.example.com` e `static.example.com`. Você pode usar uma estratégia de nomeação dinâmica com o padrão `*.example.com` a fim de identificar segmentos para cada subdomínio com um nome diferente, o que resulta em três nós de serviço no mapa de serviços. Se a aplicação receber solicitações com um nome de host que não corresponda ao padrão, você verá um quarto nó no mapa de serviços com um nome alternativo especificado por você.
Para usar o mesmo nome para todos os segmentos de solicitação, especifique o nome do seu aplicativo ao inicializar o middleware, como mostrado nas seções anteriores.
**nota**
Você pode sobrepor o nome do serviço padrão que definiu no código com a [variável de ambiente](xray-sdk-nodejs-configuration.md#xray-sdk-nodejs-configuration-envvars) `AWS_XRAY_TRACING_NAME`.
Uma estratégia de nomenclatura dinâmica define um padrão que os nomes de host devem corresponder, e um nome padrão a ser usado se o nome do host na solicitação HTTP não corresponder ao padrão. Para nomear segmentos dinamicamente, use `AWSXRay.middleware.enableDynamicNaming`.
**Example app.js – nomes de segmentos dinâmicos**
Se o nome do host na solicitação estiver em conformidade com o padrão `*.example.com`, use o nome do host. Caso contrário, use `MyApp`.
```
var app = express();
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
AWSXRay.middleware.enableDynamicNaming('*.example.com');
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment());
```
# Rastreando chamadas AWS do SDK com 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
[Quando seu aplicativo faz chamadas Serviços da AWS para armazenar dados, gravar em uma fila ou enviar notificações, o X-Ray SDK para Node.js rastreia as chamadas downstream em subsegmentos.](xray-sdk-nodejs-subsegments.md) O rastreamento Serviços da AWS e os recursos que você acessa nesses serviços (por exemplo, um bucket do Amazon S3 ou uma fila do Amazon SQS) aparecem como nós downstream no mapa de rastreamento no console X-Ray.
[Clientes AWS do Instrument SDK que você cria por meio da [AWS SDK para JavaScript V2 ou AWS SDK para JavaScript V3](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/welcome.html).](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html) Cada versão do AWS SDK fornece métodos diferentes para instrumentar clientes AWS SDK.
**nota**
Atualmente, o AWS X-Ray SDK para Node.js retorna menos informações de segmentos ao instrumentar clientes AWS SDK para JavaScript V3, em comparação com a instrumentação de clientes V2. Por exemplo, os subsegmentos que representam chamadas para o DynamoDB não retornarão o nome da tabela. Se você precisar dessas informações de segmento em seus rastreamentos, considere usar o AWS SDK para JavaScript V2.
------
#### [ AWS SDK para JavaScript V2 ]
Você pode instrumentar todos os clientes do AWS SDK V2 agrupando sua instrução `aws-sdk` require em uma chamada para. `AWSXRay.captureAWS`
**Example app.js - Instrumentação AWS do SDK**
```
const AWS = AWSXRay.captureAWS(require('aws-sdk'));
```
Para instrumentar clientes individuais, envolva seu cliente AWS SDK em uma chamada para`AWSXRay.captureAWSClient`. Por exemplo, para instrumentar um cliente `AmazonDynamoDB`:
**Example app.js: instrumentação de cliente do DynamoDB**
```
const AWSXRay = require('aws-xray-sdk');
...
const ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
```
**Atenção**
Não use `captureAWS` e `captureAWSClient` juntos. Isso resultará em subsegmentos duplicados.
Se você quiser usar [TypeScript](https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html)com [ECMAScriptmódulos](https://nodejs.org/api/esm.html) (ESM) para carregar seu JavaScript código, use o exemplo a seguir para importar bibliotecas:
**Example app.js - Instrumentação AWS do SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Para instrumentar todos os AWS clientes com ESM, use o seguinte código:
**Example app.js - Instrumentação AWS do SDK**
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
const XRAY_AWS = AWSXRay.captureAWS(AWS);
const ddb = new XRAY_AWS.DynamoDB();
```
Para todos os serviços, o nome da API chamada no console do X-Ray pode ser visto. Para um subconjunto de serviços, o X-Ray SDK adiciona informações ao segmento para fornecer maior detalhamento no mapa de serviços.
Por exemplo, quando você faz uma chamada com um cliente instrumentado do DynamoDB, o SDK adiciona o nome da tabela ao segmento para chamadas direcionadas a uma tabela. No console, cada tabela aparece como um nó separado no mapa de serviços, com um nó genérico do DynamoDB para chamadas não direcionadas a uma tabela.
**Example Subsegmento para uma chamada ao DynamoDB para salvar um item**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
Ao acessar recursos nomeados, as chamadas para os serviços os seguir criam nós adicionais no mapa de serviço. As chamadas que não apontam para recursos específicos criam um nó genérico para o serviço.
+ **Amazon DynamoDB**: nome da tabela
+ **Amazon Simple Storage Service**: nome de chave e bucket
+ **Amazon Simple Queue Service**: nome da fila
------
#### [ AWS SDK para JavaScript V3 ]
A AWS SDK para JavaScript V3 é modular, então seu código carrega apenas os módulos necessários. Por esse motivo, não é possível instrumentar todos os clientes do AWS SDK, pois a V3 não oferece suporte ao `captureAWS` método.
Se quiser usar TypeScript com ECMAScript Módulos (ESM) para carregar seu JavaScript código, você pode usar o exemplo a seguir para importar bibliotecas:
```
import * as AWS from 'aws-sdk';
import * as AWSXRay from 'aws-xray-sdk';
```
Instrumente cada cliente AWS SDK usando o `AWSXRay.captureAWSv3Client` método. Por exemplo, para instrumentar um cliente `AmazonDynamoDB`:
**Example app.js: instrumentação de cliente do DynamoDB usando o SDK para Javascript V3**
```
const AWSXRay = require('aws-xray-sdk');
const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
...
const ddb = AWSXRay.captureAWSv3Client(new DynamoDBClient({ region: "region" }));
```
Ao usar a AWS SDK para JavaScript V3, metadados como nome da tabela, nome do bucket e da chave ou nome da fila não são retornados atualmente e, portanto, o mapa de rastreamento não conterá nós discretos para cada recurso nomeado, como faria ao instrumentar clientes AWS SDK usando a V2. AWS SDK para JavaScript
**Example Subsegmento para uma chamada ao DynamoDB para salvar um item, ao usar a V3 AWS SDK para JavaScript**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
------
# Rastrear chamadas para serviços da web HTTP subsequentes usando 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
Quando seu aplicativo faz chamadas para microsserviços ou HTTP público APIs, você pode usar o cliente X-Ray SDK for Node.js para instrumentar essas chamadas e adicionar a API ao gráfico de serviços como um serviço downstream.
Passe o cliente `http` ou `https` para o método `captureHTTPs` do X-Ray SDK para Node.js a fim de rastrear chamadas de saída.
**nota**
As chamadas que usam bibliotecas de solicitação HTTP de terceiros, como Axios ou Superagent, são compatíveis com a [API `captureHTTPsGlobal()`](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/module-http_p.html) e ainda serão rastreadas quando usarem o módulo nativo `http`.
**Example app.js – Cliente HTTP**
```
var AWSXRay = require('aws-xray-sdk');
var http = AWSXRay.captureHTTPs(require('http'));
```
Para habilitar o rastreamento em todos os clientes HTTP, chame `captureHTTPsGlobal` antes de carregar `http`.
**Example app.js – Cliente HTTP (global)**
```
var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
var http = require('http');
```
Quando você instrumenta uma chamada para uma API subsequente da web, o X-Ray SDK para Node.js registra um subsegmento que contém informações sobre a solicitação e a resposta HTTP. O X-Ray usa o subsegmento para gerar um segmento inferido para a API remota.
**Example Subsegmento para uma chamada HTTP downstream**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento inferido para uma chamada HTTP de downstream**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Rastrear consultas SQL com 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
Instrumente consultas do banco de dados SQL integrando o cliente SQL ao método de cliente correspondente do X-Ray SDK para Node.js.
+ **PostgreSQL**: `AWSXRay.capturePostgres()`
```
var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();
```
+ **MySQL**: `AWSXRay.captureMySQL()`
```
var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
...
var connection = mysql.createConnection(config);
```
Quando você usa um cliente instrumentado para fazer consultas SQL, o SDK de X-Ray para Node.js registra informações sobre a conexão e a consulta em um subsegmento.
## Incluir dados adicionais em subsegmentos SQL
Você pode adicionar outras informações a subsegmentos gerados para consultas SQL, desde que sejam mapeados para um campo SQL na lista de permissões. Por exemplo, para registrar a sequência de consulta SQL limpa em um subsegmento, você pode adicioná-la diretamente ao objeto SQL do subsegmento.
**Example Atribuir SQL a um subsegmento**
```
const queryString = 'SELECT * FROM MyTable';
connection.query(queryString, ...);
// Retrieve the most recently created subsegment
const subs = AWSXRay.getSegment().subsegments;
if (subs & & subs.length > 0) {
var sqlSub = subs[subs.length - 1];
sqlSub.sql.sanitized_query = queryString;
}
```
Para obter uma lista completa de campos SQL na lista de permissões, consulte [Consultas SQL](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-sql) no *Guia do desenvolvedor do AWS X-Ray *.
# Gerar subsegmentos personalizados com o X-Ray SDK para Node.js
Os subsegmentos estendem o [segmento](xray-concepts.md#xray-concepts-segments) de um rastreamento com detalhes sobre o trabalho realizado para atender a uma solicitação. Sempre que você faz uma chamada com um cliente instrumentado, o X-Ray SDK registra as informações geradas em um subsegmento. Você pode criar subsegmentos adicionais para agrupar outros subsegmentos, medir o desempenho de uma seção do código ou registrar anotações e metadados.
## Subsegmentos Express personalizados
**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
Para criar um subsegmento personalizado para uma função que faz chamadas para serviços de downstream, use a função `captureAsyncFunc`.
**Example app.js: subsegmentos personalizados expressos**
```
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('MyApp'));
app.get('/', function (req, res) {
var host = 'api.example.com';
AWSXRay.captureAsyncFunc('send', function(subsegment) {
sendRequest(host, function() {
console.log('rendering!');
res.render('index');
subsegment.close();
});
});
});
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb) {
var options = {
host: host,
path: '/',
};
var callback = function(response) {
var str = '';
response.on('data', function (chunk) {
str += chunk;
});
response.on('end', function () {
cb();
});
}
http.request(options, callback).end();
};
```
Neste exemplo, o aplicativo cria um subsegmento personalizado denominado `send` para chamadas para a função `sendRequest`. `captureAsyncFunc` passa um subsegmento, que você deve fechar dentro da função de retorno de chamada, quando as chamadas assíncronas que ele faz são concluídas.
Para funções síncronas, você pode usar a função `captureFunc`, que fecha o subsegmento automaticamente assim que a função bloquear finaliza a execução.
Quando você cria um subsegmento dentro de um segmento ou outro subsegmento, o X-Ray SDK para Node.js; gera um ID para ele e registra a hora de início e de término.
**Example Subsegmento com metadados**
```
"subsegments": [{
"id": "6f1605cd8a07cb70",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "Custom subsegment for UserModel.saveUser function",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
```
## Subsegmentos personalizados do Lambda
O SDK é configurado para criar automaticamente um segmento de fachada de espaço reservado quando ele detecta que está sendo executado no Lambda. Para criar um subsegmento básico, que criará um único nó `AWS::Lambda::Function` no mapa de rastreamento do X-Ray, chame e reutilize o segmento de fachada. Se você criar manualmente um novo segmento com um novo ID (ao compartilhar o ID de rastreamento, o ID pai e a decisão de amostragem), será possível enviar um novo segmento.
**Example app.js: subsegmentos personalizados manuais**
```
const segment = AWSXRay.getSegment(); //returns the facade segment
const subsegment = segment.addNewSubsegment('subseg');
...
subsegment.close();
//the segment is closed by the SDK automatically
```
# Adicione anotações e metadados aos segmentos com 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 registrar informações adicionais sobre solicitações, o ambiente ou o aplicativo com anotações e metadados. Também é possível adicionar anotações e metadados aos segmentos que o X-Ray SDK cria ou aos subsegmentos personalizados que você cria.
**Anotações** são pares de chave-valor com valores boolianos, de string ou número. As anotações são indexadas para serem usadas com [expressões de filtro](xray-console-filters.md). Use anotações para registrar dados que você deseja usar para agrupar rastreamentos no console ou ao chamar a API [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html).
**Metadados** são pares chave-valor que podem ter valores de qualquer tipo, incluindo objetos e listas, mas não são indexados para uso com expressões de filtro. Use metadados para registrar dados adicionais que você deseja armazenar no rastreamento e não precisa usar com a pesquisa.
Além de anotações e metadados, você também pode [registrar strings de ID de usuário](#xray-sdk-nodejs-segment-userid) em segmentos. IDs Os usuários são registrados em um campo separado nos segmentos e são indexados para uso com a pesquisa.
**Topics**
+ [Registrar anotações com o X-Ray SDK para Node.js](#xray-sdk-nodejs-segment-annotations)
+ [Registrar metadados com o X-Ray SDK para Node.js](#xray-sdk-nodejs-segment-metadata)
+ [Gravando usuário IDs com o X-Ray SDK para Node.js](#xray-sdk-nodejs-segment-userid)
## Registrar anotações com o X-Ray SDK para Node.js
Use anotações para registrar informações em segmentos ou subsegmentos que você deseja indexar para pesquisa.
**Requisitos de anotação**
+ **Chaves**: a chave para uma anotação do X-Ray pode ter até 500 caracteres alfanuméricos. Você não pode usar espaços ou símbolos que não sejam um ponto (.)
+ **Valores**: o valor de uma anotação do X-Ray pode ter até 1.000 caracteres Unicode.
+ O número de **anotações**: você pode usar até cinquenta anotações por rastreamento.
**Como registrar anotações**
1. Obtenha uma referência para o segmento ou subsegmento.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Chame `addAnnotation` com uma chave de string e um valor de número, string ou booliano.
```
document.addAnnotation("mykey", "my value");
```
O exemplo a seguir mostra como chamar `putAnnotation` com uma chave String que inclui um ponto e um valor booliano, numérico ou de string.
```
document.putAnnotation("testkey.test", "my value");
```
O SDK registra anotações como pares de chave-valor em um objeto `annotations` no documento de segmentos. Chamar `addAnnotation` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento.
Para encontrar rastreamentos que têm anotações com valores específicos, use a palavra-chave `annotation[key]` em uma [expressão de filtro](xray-console-filters.md).
**Example app.js: anotações**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var item = {
'email': {'S': req.body.email},
'name': {'S': req.body.name},
'preview': {'S': req.body.previewAccess},
'theme': {'S': req.body.theme}
};
var seg = AWSXRay.getSegment();
seg.addAnnotation('theme', req.body.theme);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
## Registrar metadados com o X-Ray SDK para Node.js
Use metadados para registrar informações em segmentos ou subsegmentos dos quais você não precisa indexados para pesquisa. Valores de metadados podem ser strings, números, boolianos ou outro objeto que possa ser serializado em uma matriz ou objeto JSON.
**Como registrar metadados**
1. Obtenha uma referência para o segmento ou subsegmento.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Chame `addMetadata` com uma chave de string, um booliano, um número, uma string ou valor de objeto e um namespace de string.
```
document.addMetadata("my key", "my value", "my namespace");
```
or
Chame `addMetadata` com apenas uma chave e valor.
```
document.addMetadata("my key", "my value");
```
Se você não especificar um namespace, o SDK usará `default`. Chamar `addMetadata` duas vezes com a mesma chave substitui os valores registrados anteriormente no mesmo segmento ou subsegmento.
## Gravando usuário IDs com o X-Ray SDK para Node.js
Registre o usuário IDs nos segmentos da solicitação para identificar o usuário que enviou a solicitação. Essa operação não é compatível com AWS Lambda funções porque os segmentos em ambientes Lambda são imutáveis. A chamada `setUser` pode ser aplicada somente a segmentos, não a subsegmentos.
**Para gravar usuário IDs**
1. Obtenha uma referência para o segmento ou subsegmento.
```
var AWSXRay = require('aws-xray-sdk');
...
var document = AWSXRay.getSegment();
```
1. Chame `setUser()` com um ID de string do usuário que enviou a solicitação.
```
var user = 'john123';
AWSXRay.getSegment().setUser(user);
```
É possível chamar `setUser` para registrar o ID de usuário assim que o aplicativo Express iniciar o processamento de uma solicitação. Se pretende usar o segmento somente para definir o ID de usuário, é possível vincular as chamadas em uma única linha.
**Example app.js: ID de usuário**
```
var AWS = require('aws-sdk');
var AWSXRay = require('aws-xray-sdk');
var uuidv4 = require('uuid/v4');
var ddb = AWSXRay.captureAWSClient(new AWS.DynamoDB());
...
app.post('/signup', function(req, res) {
var userId = uuidv4();
var item = {
'userId': {'S': userId},
'email': {'S': req.body.email},
'name': {'S': req.body.name}
};
var seg = AWSXRay.getSegment().setUser(userId);
ddb.putItem({
'TableName': ddbTable,
'Item': item,
'Expected': { email: { Exists: false } }
}, function(err, data) {
...
```
Para encontrar rastreamentos para um ID de usuário, use a `user` palavra-chave em uma [expressão de filtragem](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html).