Configuración del X-Ray SDK para Ruby

El X-Ray SDK para Ruby tiene una clase denominada XRay.recorder que proporciona la grabadora global. Puede configurar la grabadora global para que personalice el middleware que crea los segmentos para las llamadas HTTP entrantes.

Complementos del servicio

Utilice plugins para registrar información sobre el servicio que aloja la aplicación.

Para utilizar complementos, especifíquelos en el objeto de configuración que se pasa a la grabadora.

my_plugins = %I[ec2 elastic_beanstalk]

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

XRay.recorder.configure(config)

También puede utilizar las variables de entorno, que tienen prioridad frente a los valores establecidos en código, para configurar la grabadora.

El SDK también usa la configuración del complemento para establecer el campo origin en el segmento. Indica el tipo de AWS recurso que ejecuta la aplicación. Cuando utilizas varios complementos, el SDK utiliza el siguiente orden de resolución para determinar el origen: ElasticBeanstalk > EKS > ECS > EC2.

Reglas de muestreo

El SDK utiliza las reglas de muestreo que se definen en la X-Ray consola para determinar qué solicitudes se van a registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el cinco por ciento de las solicitudes adicionales de todos los servicios a los que se envía el seguimiento X-Ray. Cree reglas adicionales en la X-Ray consola para personalizar la cantidad de datos registrados para cada una de sus aplicaciones.

El SDK aplica las reglas personalizadas en el orden en que se definen. Si una solicitud coincide con varias reglas personalizadas, el SDK solo aplica la primera regla.

También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar reglas locales como respaldo en los casos en que el X-Ray muestreo no esté disponible, o usar reglas locales 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
  }
}

En este ejemplo se define una regla personalizada y una regla predeterminada. La regla personalizada aplica un porcentaje de muestreo del 5 % sin un número mínimo de solicitudes de rastreo para las rutas incluidas bajo /api/move/. La regla predeterminada rastrea la primera solicitud cada segundo y el 10 % de las solicitudes adicionales.

La desventaja de definir las reglas de forma local es que el objetivo fijo lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser gestionado por el X-Ray servicio. A medida que se implementan más hosts, el porcentaje establecido se multiplica, lo que dificulta el control de la cantidad de datos registrados.

Para configurar reglas de copia de seguridad, defina un hash para el documento en el objeto de configuración que se pasa a la grabadora.

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 almacenar las reglas de muestreo por separado, defina el hash en un archivo independiente y haga que el archivo lo incorpore a la aplicación.

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 utilizar solo reglas locales, requiera las reglas de muestreo y configure el LocalSampler.

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

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

También puede configurar la grabadora global para deshabilitar el muestreo e instrumentar todas las solicitudes entrantes.

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

Registro

De forma predeterminada, la grabadora muestra los eventos de nivel informativo en $stdout. Puede personalizar el registro mediante la definición de un registrador en el objeto de configuración que se pasa a la grabadora.

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

Utilice registros de depuración para identificar problemas como la presencia de subsegmentos sin cerrar al generar subsegmentos de forma manual.

Configuración de la grabadora en código

Hay disponibles ajustes adicionales a partir del método configure en XRay.recorder.

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

XRay.recorder.configure(config)

Configuración de la grabadora con Rails

Si utiliza el marco de trabajo Rails, puede configurar las opciones de la grabadora global en un archivo de Ruby situado en app_root/initializers. El X-Ray SDK admite una clave de configuración adicional para su uso con Rails.

Configure los ajustes disponibles en un objeto de configuración denominado Rails.application.config.xray.

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

Variables de entorno

Puedes usar variables de entorno para configurar el X-Ray SDK para Ruby. El SDK admite las siguientes variables:

Las variables de entorno anulan los valores establecidos en el código.