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. # AWS X-Ray SDK for 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 es una biblioteca para las aplicaciones web de Ruby que proporciona clases y métodos para generar y enviar datos de rastreo al daemon de X-Ray. Los datos de rastreo incluyen información sobre las solicitudes HTTP entrantes atendidas por la aplicación y las llamadas que la aplicación realiza a los servicios descendentes mediante el AWS SDK, los clientes HTTP o un cliente de registro activo. También puede crear segmentos de forma manual y agregar información de depuración en anotaciones y metadatos. Puede descargar el SDK añadiéndolo a su archivo Gemfile y ejecutando `bundle install`. **Example Archivo Gemfile** ``` gem 'aws-sdk' ``` Si utiliza Rails, en primer lugar [añada el middleware del SDK de X-Ray](xray-sdk-ruby-middleware.md) para rastrear las solicitudes entrantes. Un filtro de solicitudes crea un [segmento](xray-concepts.md#xray-concepts-segments). Mientras el segmento está abierto, puede utilizar los métodos del cliente del SDK para añadir información al segmento y crear subsegmentos para rastrear llamadas posteriores. El SDK también registra automáticamente las excepciones que produce su aplicación mientras el segmento está abierto. Para las aplicaciones que no son de Rails, puede [crear segmentos manualmente](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual). A continuación, utilice el SDK de X-Ray para AWS SDK para Ruby instrumentar sus clientes HTTP y SQL [configurando la grabadora](xray-sdk-ruby-patching.md) para que aplique parches a las bibliotecas asociadas. Cada vez que realizas una llamada a un recurso Servicio de AWS o a un canal intermedio con un cliente instrumentado, el SDK registra la información sobre la llamada en un subsegmento. Servicios de AWS y los recursos a los que accedes desde los servicios aparecen como nodos descendentes en el mapa de rastreo para ayudarte a identificar los errores y los problemas de limitación en las conexiones individuales. En cuanto empiece a utilizar el SDK, personalice su comportamiento [configurando la grabadora](xray-sdk-ruby-configuration.md). Puede añadir complementos para registrar datos sobre los recursos informáticos que ejecutan la aplicación, personalizar el comportamiento de muestreo mediante la definición de reglas de muestreo y proporcionar un registrador para ver más o menos información del SDK en los logs de la aplicación. Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza en [anotaciones y metadatos](xray-sdk-ruby-segment.md). Las anotaciones son pares sencillos de clave-valor que se indexan para su uso con [expresiones de filtro](xray-console-filters.md) para poder buscar rastros que contengan datos específicos. Las entradas de metadatos son menos restrictivas y pueden registrar objetos y matrices completos, es decir, todo lo que se pueda serializar en JSON. **Anotaciones y metadatos** Las anotaciones y los metadatos son texto arbitrario que se agrega a los segmentos con el SDK de X-Ray. Las anotaciones se indexan para su uso con expresiones de filtro. Los metadatos no se indexan pero se pueden ver en el segmento sin procesar con la consola o la API de X-Ray. Cualquier persona a la que conceda acceso de lectura a X-Ray puede ver estos datos. Cuando tenga muchos clientes instrumentados en su código, un único segmento de solicitud puede contener un gran número de subsegmentos, uno para cada llamada realizada con un cliente instrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente en [subsegmentos personalizados](xray-sdk-ruby-subsegments.md). Puede crear un subsegmento personalizado para una función completa o para cualquier sección de código, y registrar los metadatos y las anotaciones en el subsegmento en lugar de escribirlo todo en el segmento principal. Para acceder a la documentación de referencia de las clases y los métodos del SDK, consulte la [Referencia de la API del SDK de AWS X-Ray para Ruby](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference). ## Requisitos El SDK de X-Ray requiere Ruby 2.3 o posterior y es compatible con las siguientes bibliotecas: + AWS SDK para Ruby versión 3.0 o posterior + Rails versión 5.1 o posterior # 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. # Rastreo de las solicitudes entrantes con el SDK de X-Ray para middleware de 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 Puede usar el SDK de X-Ray para rastrear las solicitudes HTTP entrantes que su aplicación sirve en una instancia EC2 de Amazon EC2 AWS Elastic Beanstalk o Amazon ECS. Si utiliza Rails, use el middleware de Rails para instrumentar las solicitudes HTTP entrantes. Cuando añade el middleware a su aplicación y configura un nombre de segmento, el SDK de X-Ray para Ruby crea un segmento para cada solicitud muestreada. Cualquier segmento que se haya creado con instrumentación adicional se convierte en subsegmentos del segmento en nivel de la solicitud, el cual provee información sobre la solicitud HTTP y la respuesta. Esta información incluye el momento, el método y la disposición de la solicitud. Cada segmento tiene un nombre que identifica la aplicación en el mapa de servicio. El nombre del segmento se puede asignar de forma estática o se puede configurar el SDK para que le asigne un nombre dinámico en función del encabezado del host de la solicitud entrante. La nomenclatura dinámica permite agrupar los rastros en función del nombre de dominio de la solicitud y aplicar un nombre predeterminado si el nombre no coincide con el patrón esperado (por ejemplo, si el encabezado del host está falsificado). **Solicitudes reenviadas** Si un equilibrador de carga u otro intermediario reenvía una solicitud a la aplicación, X-Ray toma la IP de cliente del encabezado `X-Forwarded-For` de la solicitud en lugar de tomar la IP de origen del paquete IP. La IP de cliente que se graba para una solicitud reenviada puede estar falsificada, por lo que no se debe confiar en ella. Cuando se reenvía una solicitud, el SDK crea un campo adicional en el segmento para indicar que se realizó esta acción. Si el segmento contiene el campo `x_forwarded_for` configurado en `true`, el IP del cliente se obtiene a partir del encabezado `X-Forwarded-For` en la solicitud HTTP. El middleware crea un segmento para cada solicitud entrante con un bloque `http` que contiene la siguiente información: + **Método HTTP**: GET, POST, PUT, DELETE, etc. + **Dirección del cliente**: la dirección IP del cliente que envió la solicitud. + **Código de respuesta**: el código de respuesta HTTP para la solicitud finalizada. + **Intervalo**: la hora de inicio (cuando se recibió la solicitud) y la hora de finalización (cuando se envió la respuesta). + **Agente del usuario**: el `user-agent` de la solicitud. + **Longitud del contenido**: la `content-length` de la respuesta. ## Uso del middleware de Rails Para utilizar el middleware, actualice el archivo Gemfile para que incluya el [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html) necesario. **Example Archivo Gemfile: rails** ``` gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie'] ``` Para utilizar el middleware, también debe [configurar la grabadora](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails) con un nombre que represente a la aplicación en el mapa de rastros. **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app' } ``` ## Instrumentación manual del código Si no utiliza Rails, cree los segmentos manualmente. Puede crear un segmento para cada solicitud entrante o crear segmentos alrededor de clientes HTTP o AWS SDK parcheados para proporcionar contexto a la grabadora y añadir subsegmentos. ``` # Start a segment segment = XRay.recorder.begin_segment 'my_service' # Start a subsegment subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote' # Add metadata or annotation here if necessary my_annotations = { k1: 'v1', k2: 1024 } segment.annotations.update my_annotations # Add metadata to default namespace subsegment.metadata[:k1] = 'v1' # Set user for the segment (subsegment is not supported) segment.user = 'my_name' # End segment/subsegment XRay.recorder.end_subsegment XRay.recorder.end_segment ``` ## Configuración de una estrategia de nomenclatura de segmentos AWS X-Ray utiliza un *nombre de servicio* para identificar la aplicación y distinguirla del resto de aplicaciones, bases de datos, recursos externos APIs y otros AWS recursos que utiliza la aplicación. Cuando el SDK de X-Ray genera segmentos para las solicitudes entrantes, registra el nombre del servicio de la aplicación en el [campo de nombre](xray-api-segmentdocuments.md#api-segmentdocuments-fields) del segmento. El SDK de X-Ray puede nombrar los segmentos utilizando el nombre de host en el encabezado de la solicitud HTTP. Sin embargo, este encabezado se puede falsificar, lo que podría provocar nodos inesperados en el mapa de servicio. Para evitar que el SDK nombre los segmentos de forma incorrecta debido a que las solicitudes tienen encabezados de host falsificados, debe especificar un nombre predeterminado para las solicitudes entrantes. Si la aplicación atiende solicitudes de varios dominios, puede configurar el SDK para que utilice una estrategia de nomenclatura dinámica que refleje esto en los nombres de los segmentos. Una estrategia de nomenclatura dinámica permite al SDK usar el nombre de host para las solicitudes que coinciden con un patrón esperado y aplicar el nombre predeterminado a las solicitudes que no coincidan. Por ejemplo, es posible que tenga una sola aplicación que atienda solicitudes a tres subdominios: `www.example.com`, `api.example.com` y `static.example.com`. Puede usar una estrategia de nomenclatura dinámica con el patrón `*.example.com` para identificar los segmentos de cada subdominio con un nombre diferente, lo que da como resultado tres nodos de servicio en el mapa de servicio. Si su aplicación recibe solicitudes con un nombre de host que no coincide con el patrón, verá un cuarto nodo en el mapa de servicio con el nombre alternativo que especifique. Si desea utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de la aplicación cuando configure la grabadora, como se muestra en las [secciones anteriores](#xray-sdk-ruby-middleware-rails). Una estrategia de nomenclatura dinámica define un patrón con el que deben coincidir los nombres de host y un nombre predeterminado que se utiliza si el nombre de host de la solicitud HTTP no coincide con el patrón. Para asignar nombre a los segmentos de forma dinámica, especifique un patrón de nomenclatura en el hash config. **Example main.rb: nomenclatura dinámica** ``` config = { naming_pattern: '*mydomain*', name: 'my app', } XRay.recorder.configure(config) ``` Puede utilizar "\$1" en el patrón para buscar coincidencia con cualquier cadena o "?" para buscar coincidencias con cualquier carácter único. **nota** Puede anular el nombre de servicio predeterminado que ha definido en el código mediante la `AWS_XRAY_TRACING_NAME`variable de entorno[Variables de entorno](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars). # Aplicación de parches a bibliotecas para instrumentar llamadas posteriores **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 Para instrumentar llamadas posteriores, utilice el SDK de X-Ray para Ruby con el fin de aplicar parches a las bibliotecas que utiliza la aplicación. El SDK de X-Ray para Ruby puede aplicar parches a las siguientes bibliotecas. **Bibliotecas compatibles** + `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)`: instrumente clientes HTTP. + `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)`— Clientes de instrumentos. AWS SDK para Ruby Al utilizar una biblioteca con parches, el SDK de X-Ray para Ruby crea un subsegmento para la llamada y registra información desde la solicitud y la respuesta. Debe haber un segmento disponible para que el SDK cree el subsegmento, ya sea desde el middleware del SDK o mediante una llamada a `XRay.recorder.begin_segment`. Para aplicar parches a las bibliotecas, especifíquelos en el objeto de configuración que se pasa a la grabadora de X-Ray. **Example main.rb: aplique parches a las bibliotecas** ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http aws_sdk] } XRay.recorder.configure(config) ``` # Rastreo de llamadas al AWS SDK con el 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 [Cuando tu aplicación realiza llamadas Servicios de AWS para almacenar datos, escribir en una cola o enviar notificaciones, el X-Ray SDK for Ruby rastrea las llamadas en sentido descendente en subsegmentos.](xray-sdk-ruby-subsegments.md) El rastreo Servicios de AWS y los recursos a los que accede dentro de esos servicios (por ejemplo, un bucket de Amazon S3 o una cola de Amazon SQS) aparecen como nodos descendentes en el mapa de rastreo de la consola X-Ray. El X-Ray SDK for Ruby instrumenta automáticamente todos los clientes AWS del SDK cuando se aplica [un parche a la `aws-sdk` biblioteca](xray-sdk-ruby-patching.md). No puede instrumentar clientes individuales. Para todos los servicios, puede ver el nombre de la API a la que se llama en la consola de X-Ray. Para un subconjunto de servicios, el SDK de X-Ray agrega información al segmento para proporcionar una mayor granularidad en el mapa de servicio. Por ejemplo, cuando realiza una llamada con un cliente instrumentado de DynamoDB, el SDK agrega el nombre de tabla al segmento para las llamadas que se dirigen a una tabla. En la consola, cada tabla aparece como nodo independiente en el mapa de servicio, con un nodo genérico de DynamoDB para las llamadas que no se dirigen a una tabla. **Example Subsegmento para una llamada a DynamoDB con el fin de guardar un elemento** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` Cuando accede a recursos designados, las llamadas a los siguientes servicios crean nodos adicionales en el mapa de servicio. Las llamadas que no están dirigidas a recursos concretos crean un nodo genérico en el servicio. + **Amazon DynamoDB**: nombre de tabla + **Amazon Simple Storage Service**: nombre de bucket y de clave + **Amazon Simple Queue Service**: nombre de cola # Generación de subsegmentos personalizados con el SDK de X-Ray **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 Los subsegmentos amplían el [segmento](xray-concepts.md#xray-concepts-segments) de un rastro con detalles sobre el trabajo realizado para atender una solicitud. Cada vez que usted realiza una llamada con un cliente instrumentado, el SDK de X-Ray registra la información generada en un subsegmento. Puede crear subsegmentos adicionales para agrupar otros subsegmentos, medir el rendimiento de una sección de código o registrar anotaciones y metadatos. Para administrar los subsegmentos, utilice los métodos `begin_subsegment` y `end_subsegment`. ``` subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote' my_annotations = { id: 12345 } subsegment.annotations.update my_annotations XRay.recorder.end_subsegment ``` Para crear un subsegmento para una función, encapsúlelo en una llamada a `XRay.recorder.capture`. ``` XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' resp end ``` Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el SDK de X-Ray genera un ID para dicho subsegmento y registra la hora de inicio y la hora de finalización. **Example Subsegmentos con metadatos** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` # Adición de anotaciones y metadatos a los segmentos con el 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 Puede registrar información adicional acerca de las solicitudes, el entorno o su aplicación con anotaciones y metadatos. Puede añadir anotaciones y metadatos a los segmentos que crea el SDK de X-Ray o a los subsegmentos personalizados que cree usted mismo. Las **anotaciones** son pares de clave-valor con valores de cadena, numéricos o booleanos. Las anotaciones se indexan para su uso con [expresiones de filtro](xray-console-filters.md). Utilice anotaciones para registrar los datos que desee utilizar para agrupar rastros en la consola o cuando llame a la API de [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html). Los **metadatos** son pares de clave-valor con valores de cualquier tipo, por ejemplo objetos y listas, pero que no se indexan para utilizarlos con expresiones de filtro. Utilice los metadatos para registrar datos adicionales que desee almacenar en el rastro, pero que no necesite usar para hacer búsquedas. Además de anotaciones y metadatos, también puede [registrar cadenas de ID de usuario](#xray-sdk-ruby-segment-userid) en los segmentos. IDs Los usuarios se registran en un campo independiente en los segmentos y se indexan para usarlos en la búsqueda. **Topics** + [Registro de anotaciones con el SDK de X-Ray para Ruby](#xray-sdk-ruby-segment-annotations) + [Registro de metadatos con el SDK de X-Ray para Ruby](#xray-sdk-ruby-segment-metadata) + [Grabación del usuario IDs con el SDK de X-Ray para Ruby](#xray-sdk-ruby-segment-userid) ## Registro de anotaciones con el SDK de X-Ray para Ruby Utilice anotaciones para registrar información sobre segmentos o subsegmentos que desee indexar para las búsquedas. **Requisitos de anotación** + **Claves**: la clave de una anotación de X-Ray puede contener hasta 500 caracteres alfanuméricos. No se pueden usar espacios ni símbolos, excepto el punto (.) + **Valores**: el valor de una anotación de X-Ray puede contener hasta 1000 caracteres Unicode. + Número de **anotaciones**: se pueden utilizar hasta 50 anotaciones por rastro. **Para registrar anotaciones** 1. Obtenga una referencia al segmento o subsegmento actual desde `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` o ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Llame a `update` con un valor hash. ``` my_annotations = { id: 12345 } document.annotations.update my_annotations ``` El siguiente es un ejemplo que muestra cómo llamar a `update` con una clave de anotación que contiene un punto. ``` my_annotations = { testkey.test: 12345 } document.annotations.update my_annotations ``` El SDK registra las anotaciones como pares de clave-valor en un objeto `annotations` del documento de segmento. Si llama dos veces a `add_annotations` con la misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento. Para encontrar rastros que tengan anotaciones con valores específicos, utilice la palabra clave `annotation[key]` en una [expresión de filtro](xray-console-filters.md). ## Registro de metadatos con el SDK de X-Ray para Ruby Utilice los metadatos para registrar información sobre segmentos o subsegmentos que no necesite indexar para las búsquedas. Los valores de metadatos pueden ser cadenas, números, booleanos o cualquier objeto que se pueda serializar en un objeto o matriz JSON. **Para registrar metadatos** 1. Obtenga una referencia al segmento o subsegmento actual desde `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` o ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. Llame a `metadata` con una clave de cadena; un valor booleano, numérico, de cadena o de objeto y un espacio de nombres de cadena. ``` my_metadata = { my_namespace: { key: 'value' } } subsegment.metadata my_metadata ``` Si llama dos veces a `metadata` con la misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento. ## Grabación del usuario IDs con el SDK de X-Ray para Ruby Registre IDs el usuario en los segmentos de solicitud para identificar al usuario que envió la solicitud. **Para registrar al usuario IDs** 1. Obtenga una referencia al segmento actual desde `xray_recorder`. ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 1. Especifique el ID de cadena del usuario que envió la solicitud en el campo de usuario del segmento. ``` segment.user = 'U12345' ``` Puede establecer el usuario en los controladores para registrar el ID de usuario tan pronto como la aplicación comience a procesar la solicitud. Para buscar rastros de un ID de usuario, utilice la palabra clave `user` en una [expresión de filtro](xray-console-filters.md).