Configurando o X-Ray SDK para Ruby

O X-Ray SDK for Ruby tem uma XRay.recorder classe chamada 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 o aplicativo.

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 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 X-Ray console para determinar quais solicitações devem ser registradas. A regra padrão rastreia a primeira solicitação a cada segundo e cinco por cento de todas as solicitações adicionais em todos os serviços que enviam rastreamentos para X-Ray. Crie regras adicionais no X-Ray console para personalizar a quantidade de dados gravados para cada um dos seus 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.

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 X-Ray amostragem não está disponível ou usar regras locais exclusivamente.

{
  "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 alvo fixo é aplicado por cada instância do gravador de forma independente, em vez de ser gerenciado pelo X-Ray serviço. À 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 o framework do Rails, pode configurar as opções do gravador global em um arquivo Ruby em app_root/initializers. O X-Ray SDK suporta uma chave de configuração adicional para uso 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

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

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