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.

Para usar um plug-in, configure o cliente do X-Ray SDK para Node.js usando o método config.

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 recurso da AWS que executa a aplicação. Quando você utiliza 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.

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.

{
  "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.

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

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.

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.

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.

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.

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.