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 X-Ray SDK para Ruby **nota** X-Ray SDK/Daemon Aviso de mantenimiento: el 25 de febrero de 2026, AWS X-Ray SDKs/Daemon entrará en modo de mantenimiento, en el que 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 X-Ray instrumentación a otra. OpenTelemetry ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html) 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. **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. ![Segmente los datos de recursos con los complementos de Amazon EC2 y Elastic Beanstalk.](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 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](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 obtener las reglas de muestreo, vuelve a utilizar una regla local predeterminada que establece la primera solicitud cada segundo y el cinco por ciento de las solicitudes adicionales por host. X-Ray Esto puede ocurrir si el anfitrión no tiene permiso para llamar a las API de muestreo o no puede conectarse al X-Ray daemon, que actúa como proxy TCP para las llamadas a las API que realiza el SDK. 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. **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 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. **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`— Configura el host y el puerto del daemon listener. 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 X-Ray SDK 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\_xray.rb** ``` 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: + `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`— Configura el host y el puerto del X-Ray daemon listener. 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.