Configurar o X-Ray SDK para Ruby

O X-Ray SDK para Ruby tem uma classe chamada XRay.recorder, que fornece o gravador global. Você pode configurar o gravador global para personalizar o middleware que cria segmentos para chamadas HTTP de entrada.

Plug-ins de serviço

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

Para usar plug-ins, você deve especificá-los no objeto de configuração que passa ao gravador.

my_plugins = %I[ec2 elastic_beanstalk]

config = {
  plugins: my_plugins,
  name: 'my app',
}

XRay.recorder.configure(config)

Você também pode usar variáveis de ambiente, que têm precedência sobre valores definidos no código, para configurar o gravador.

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.

Para configurar regras de backup, defina um hash para o documento no objeto de configuração que você passa para o gravador.

require 'aws-xray-sdk'
my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}
config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)

Para armazenar as regras de amostragem de forma independente, defina o hash em um arquivo separado e exija que o arquivo o inclua em seu aplicativo.

my_sampling_rules =  {
  version: 1,
  default: {
    fixed_target: 1,
    rate: 0.1
  }
}

require 'aws-xray-sdk'
require 'config/sampling-rules.rb'

config = {
  sampling_rules: my_sampling_rules,
  name: 'my app',
}
XRay.recorder.configure(config)

Para usar apenas regras locais, exija as regras de amostragem e configure o LocalSampler.

require 'aws-xray-sdk'
require 'aws-xray-sdk/sampling/local/sampler'

config = {
  sampler: LocalSampler.new,
  name: 'my app',
}
XRay.recorder.configure(config)

Você também pode configurar o gravador global para desabilitar a amostragem e instrumentar todas as solicitações de entrada.

require 'aws-xray-sdk'
config = {
  sampling: false,
  name: 'my app',
}
XRay.recorder.configure(config)

Registro em log

Por padrão, o gravador encaminha os eventos informativos para $stdout. Você pode personalizar o registro em log definindo um registrador no objeto de configuração que você passa para o gravador.

require 'aws-xray-sdk'
config = {
  logger: my_logger,
  name: 'my app',
}
XRay.recorder.configure(config)

Use logs de depuração para identificar problemas como subsegmentos não fechados ao gerar subsegmentos manualmente.

Configuração do gravador no código

Configurações adicionais estão disponíveis no método configure no XRay.recorder.

require 'aws-xray-sdk'
config = {
  context_missing: 'LOG_ERROR'
}

XRay.recorder.configure(config)

Configuração do gravador com o rails

Se você usa a estrutura do Rails, pode configurar as opções do gravador global em um arquivo Ruby em app_root/initializers. O X-Ray SDK aceita uma chave de configuração adicional para usar com o Rails.

Defina as configurações disponíveis em um objeto de configuração denominado Rails.application.config.xray.

Rails.application.config.xray = {
  name: 'my app',
  patch: %I[net_http aws_sdk],
  active_record: true
}

Variáveis de ambiente

É possível usar variáveis de ambiente para configurar o X-Ray SDK para Ruby. O SDK é compatível com as seguintes variáveis:

As variáveis de ambiente substituem os valores definidos no código.