AWS X-Ray SDK para Node.js - AWS X-Ray
RequisitosGerenciar dependênciasAmostras de Node.jsConfiguraçãoSolicitações de entradaChamadas HTTP de saídaConsultas SQLSubsegmentos personalizadosAnotações e metadados

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á.

AWS X-Ray SDK para Node.js

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 X-Ray SDK para Node.js é um projeto de código aberto compatível com as versões 14.x e superiores do Node.js. Você pode acompanhar o projeto e enviar problemas e pull requests em GitHub: github.com/aws/ aws-xray-sdk-node

Se você usa o Express, comece adicionando o SDK como middleware em seu servidor de aplicativo para rastrear solicitações recebidas. O middleware cria um segmento 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 uma aplicação ou um serviço instrumentado, o Lambda lê o cabeçalho de rastreamento e rastreia automaticamente as solicitações amostradas. Para outras funções, você pode configurar o Lambda 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 e AWS X-Ray Para mais informações.

Em seguida, use o X-Ray SDK para Node.js para instrumentar seu AWS SDK JavaScript em clientes Node.js. 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 subsequentes para APIs da web HTTP e consultas SQL. Encapsule seu cliente HTTP no método de captura do SDK 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.

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 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 a aplicação faz em anotações e metadados. Anotações são simples pares de chave-valor que são indexados para serem usados com expressões de filtro 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. 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.

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

Gerenciar dependências

O X-Ray SDK para Node.js está disponível no NPM.

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.

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.

Configurar o X-Ray SDK para Node.js

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.

Plug-ins de serviço

Use plugins para registrar informações sobre o serviço que hospeda a aplicação.

Plug-ins

  • 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.

exemplo 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 para personalizar a quantidade de dados registrados para cada uma das aplicações.

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 reverte para uma regra local padrão da primeira solicitação recebida no início de cada segundo e cinco por cento de todas as solicitações adicionais por host. Isso pode ocorrer se o host não tiver permissão para chamar APIs de amostragem ou não conseguir se conectar ao daemon do X-Ray, que atua como um proxy de 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.

exemplo 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.

exemplo 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.

exemplo 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.

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.

exemplo 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 por endereço IPv4.

exemplo 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.

exemplo 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.

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 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_XRAY_DEBUG_MODE está 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.

Rastrear solicitações de entrada com o X-Ray SDK para Node.js

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 à aplicação, 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 e AWS X-Ray Para mais informações.

Cada segmento tem um nome que identifica a aplicação 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 a aplicação, 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.

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.

exemplo 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.

exemplo 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 externas e AWS recursos que seu aplicativo usa. Quando o X-Ray SDK gera segmentos para solicitações recebidas, ele registra o nome do serviço da aplicação no campo de nome 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 a aplicação 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 única aplicação 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 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.

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

Rastrear chamadas para serviços da web HTTP subsequentes usando o X-Ray SDK para Node.js

Quando a aplicação faz chamadas para microsserviços ou APIs HTTP públicas, você pode usar o cliente X-Ray SDK para Node.js para instrumentar essas chamadas e adicionar a API ao gráfico de serviço como um serviço subsequente.

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() e ainda serão rastreadas quando usarem o módulo nativo http.

exemplo 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.

exemplo 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.

exemplo 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
    }
  }
}
exemplo 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

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.

exemplo 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 dos campos SQL listados como permitidos, consulte a seção Consultas SQL no. Documentos do segmento X-Ray

Gerar subsegmentos personalizados com o X-Ray SDK para Node.js

Os subsegmentos estendem o segmento 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

Para criar um subsegmento personalizado para uma função que faz chamadas para serviços de downstream, use a função captureAsyncFunc.

exemplo 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.

exemplo 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 AWS::Lambda::Function nó no mapa de rastreamento X-Ray, chame e reutilize o segmento da 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.

exemplo 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

Você pode usar anotações e metadados para registrar informações adicionais sobre solicitações, o ambiente ou seu aplicativo. 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. Use anotações para registrar dados que você deseja usar para agrupar rastreamentos no console ou ao chamar a API GetTraceSummaries.

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 em segmentos. Os IDs de usuário são registrados em um campo separado nos segmentos e são indexados para serem usados com pesquisa.

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

  • Teclas — A chave para uma anotação de X-Ray pode ter até 500 caracteres alfanuméricos. Você não pode usar espaços ou símbolos além do símbolo de sublinhado (_).

  • Valores — O valor de uma anotação X-Ray pode ter até 1.000 caracteres Unicode.

  • O número de anotações — Você pode usar até 50 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();

  2. Chame addAnnotation com uma chave de string e um valor de número, string ou booleano.

    document.addAnnotation("mykey", "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 annotations.key em uma expressão de filtro.

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

  2. 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");

    ou

    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.

Registrar IDs de usuário com o X-Ray SDK para Node.js

Registre IDs de usuário em segmentos de 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 registrar IDs de usuário

  1. Obtenha uma referência para o segmento ou subsegmento.

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

  2. 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.

exemplo 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.