Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Configuración del SDK de X-Ray para Ruby **nota** Aviso de SDK/Daemon mantenimiento de X-Ray: el 25 de febrero de 2026, el AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, donde AWS se limitarán las versiones de X-Ray SDK y Daemon para abordar únicamente los problemas de seguridad. Para obtener más información sobre la cronología del soporte, consulte [Cronología de X-Ray SDK y Daemon Support](xray-sdk-daemon-timeline.md). Recomendamos migrar a. OpenTelemetry Para obtener más información sobre la migración a OpenTelemetry, consulte [Migración de una instrumentación de rayos X a una instrumentación](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html). OpenTelemetry 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. **Topics** + [Complementos del servicio](#xray-sdk-ruby-configuration-plugins) + [Reglas de muestreo](#xray-sdk-ruby-configuration-sampling) + [Registro](#xray-sdk-ruby-configuration-logging) + [Configuración de la grabadora en código](#xray-sdk-ruby-configuration-code) + [Configuración de la grabadora con Rails](#xray-sdk-ruby-middleware-configuration-rails) + [Variables de entorno](#xray-sdk-ruby-configuration-envvars) ## Complementos del servicio Utilice `plugins` para registrar información sobre el servicio que aloja la aplicación. **Plugins** + 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. ![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) Para utilizar complementos, especifíquelos en el objeto de configuración que se pasa a la grabadora. **Example 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](#xray-sdk-ruby-configuration-envvars), 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](xray-console-sampling.md) 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 una regla local predeterminada de la primera solicitud cada segundo y del 5 % de las solicitudes adicionales por host. Esto puede ocurrir si el host no tiene permiso para llamar al muestreo APIs o no puede conectarse al daemon X-Ray, que actúa como proxy TCP para las llamadas a la 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. **Example 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. **Example 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. **Example config/sampling-rules.rb** ``` my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } ``` **Example 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`. **Example 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. **Example 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](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) en el objeto de configuración que se pasa a la grabadora. **Example 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](xray-sdk-ruby-subsegments.md). ## 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](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming). + `plugins`: registre información acerca de los recursos de AWS de su aplicación con [complementos](#xray-sdk-ruby-configuration-plugins). + `sampling`: establezca esta opción en `false` para deshabilitar el muestreo. + `sampling_rules`: establezca el hash que contiene las [reglas de muestreo](#xray-sdk-ruby-configuration-sampling). **Example 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`. **Example config/initializers/aws\$1xray.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](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming) 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](xray-daemon-configuration.md) 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.