Configuración del SDK de X-Ray para Ruby

El SDK de X-Ray 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.

Complementos

• Amazon EC2: ec2 añade el ID y la zona de disponibilidad de la instancia.

• Elastic Beanstalk: elastic_beanstalk añade el nombre de entorno, la etiqueta de versión y el ID de implementación.

• Amazon ECS: ecs agrega el ID de contenedor.

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

ejemplo main.rb: configuración de complementos

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 define el usuario en la consola de X-Ray para determinar qué solicitudes registrar. La regla predeterminada rastrea la primera solicitud cada segundo y el 5 % de las solicitudes adicionales de todos los servicios que envían rastros a X-Ray. Cree reglas adicionales en la consola de X-Ray 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.

nota

Si el SDK no puede comunicarse con X-Ray para obtener las reglas de muestreo, vuelve a la regla local predeterminada de la primera solicitud recibida al principio de cada segundo y del cinco por ciento de las solicitudes adicionales por host. Eso puede ocurrir si el host no tiene permiso para llamar a las API de muestreo o no puede conectarse al daemon de X-Ray, que actúa como proxy TCP para las llamadas a las API realizadas por el SDK.

También puede configurar el SDK para que cargue las reglas de muestreo desde un documento JSON. El SDK puede usar las reglas locales como respaldo para los casos en que el muestreo de X-Ray no esté disponible, o puede usar las reglas locales exclusivamente.

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

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 localmente es que el objetivo establecido lo aplica cada instancia de la grabadora de forma independiente, en lugar de ser administrado por el servicio de X-Ray. 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.

ejemplo main.rb: configuración de la regla de copia de seguridad

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.

ejemplo config/sampling-rules.rb

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

ejemplo main.rb: regla de muestreo desde un archivo

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.

ejemplo main.rb: muestreo con reglas locales

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.

ejemplo main.rb: inhabilitar el muestreo

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.

ejemplo main.rb: registro

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.

• context_missing: establezca esta opción en LOG_ERROR para evitar que se produzcan excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.

• daemon_address: establezca el host y el puerto del oyente del daemon de X-Ray.

• name: establezca un nombre de servicio que el SDK utiliza para los segmentos.

• naming_pattern: establezca un patrón de asignación de nombres de dominio para utilizar la nomenclatura dinámica.

• plugins: registre información acerca de los recursos de AWS de su aplicación con complementos.

• sampling: establezca esta opción en false para deshabilitar el muestreo.

• sampling_rules: establezca el hash que contiene las reglas de muestreo.

ejemplo main.rb: deshabilite excepciones de falta de contexto

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 SDK de X-Ray admite una clave de configuración adicional para su uso con Rails.

• active_record: establezca esta opción en true para registrar subsegmentos para las transacciones de la base de datos de grabación activa.

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

ejemplo config/initializers/aws_xray.rb

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

Variables de entorno

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

• AWS_XRAY_TRACING_NAME: establezca un nombre de servicio que el SDK utiliza para los segmentos. Anula el nombre de servicio que se ha establecido en la estrategia de nomenclatura de segmento del filtro de servlet.

• AWS_XRAY_DAEMON_ADDRESS: establezca el host y el puerto del oyente del daemon de X-Ray. De forma predeterminada, el SDK envía los datos de rastreo a 127.0.0.1:2000. Use esta variable si ha configurado el daemon para que escuche en un puerto diferente o si se ejecuta en un host diferente.

• AWS_XRAY_CONTEXT_MISSING: establezca esta opción en RUNTIME_ERROR para generar excepciones cuando el código instrumentado intente registrar datos sin que haya ningún segmento abierto.

  Valores válidos

  • RUNTIME_ERROR: lance una excepción de tiempo de ejecución.

  • LOG_ERROR: registre un error y continúe (predeterminado).

  • IGNORE_ERROR: ignore el error y continúe.

  Se pueden producir errores relativos a segmentos o subsegmentos inexistentes al intentar usar un cliente instrumentado en el código de inicio que se ejecuta cuando no hay ninguna solicitud abierta o en el código que inicia un nuevo subproceso.

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