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 Java
**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 Java es un conjunto de bibliotecas para aplicaciones web Java que proporcionan 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 conector de base de datos SQL. También puede crear segmentos de forma manual y agregar información de depuración en anotaciones y metadatos.
El SDK de X-Ray para Java es un proyecto de código abierto. Puedes seguir el proyecto y enviar las incidencias y solicitudes de cambios en GitHub: [github. com/aws/aws](https://github.com/aws/aws-xray-sdk-java)- xray-sdk-java
Comience [añadiendo `AWSXRayServletFilter` como filtro de servlet](xray-sdk-java-filters.md) para rastrear las solicitudes entrantes. Los filtros de servlets crean 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.
A partir de la versión 1.3, puede instrumentar una aplicación mediante la [programación orientada a aspectos (AOP) de Spring](xray-sdk-java-aop-spring.md). Lo que esto significa es que puede instrumentar su aplicación, mientras está en ejecución AWS, sin añadir ningún código al tiempo de ejecución de la aplicación.
A continuación, utilice el SDK de X-Ray para Java para instrumentar a sus AWS SDK para Java clientes mediante [la inclusión del submódulo SDK Instrumentor](#xray-sdk-java-dependencies) en la configuración de compilación. Cada vez que realizas una llamada a un recurso Servicio de AWS o a un servicio 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.
Si no quieres instrumentar todas las llamadas posteriores Servicios de AWS, puedes omitir el submódulo Instrumentor y elegir los clientes a los que quieres instrumentar. Instrumente a los clientes individuales [añadiendo un `TracingHandler` a un](xray-sdk-java-awssdkclients.md) cliente de servicio AWS del SDK.
Otros submódulos de X-Ray SDK for Java proporcionan instrumentación para llamadas posteriores a bases de datos HTTP web APIs y SQL. Puede [utilizar las versiones de `HTTPClient` y `HTTPClientBuilder` del SDK de X-Ray para Java](xray-sdk-java-httpclients.md) en el submódulo Apache HTTP para instrumentar clientes Apache HTTP. Para instrumentar consultas SQL, [añada el interceptor del SDK al origen de datos](xray-sdk-java-sqlclients.md).
En cuanto empiece a utilizar el SDK, personalice su comportamiento [configurando la grabadora y el filtro de servlet](xray-sdk-java-configuration.md). Puede añadir complementos para registrar los datos sobre los recursos informáticos que ejecutan su aplicación, personalizar el comportamiento de muestreo mediante la definición de reglas de muestreo y definir el nivel de log para ver más o menos información del SDK en los logs de las aplicaciones.
Registre información adicional acerca de las solicitudes y el trabajo que la aplicación realiza en [anotaciones y metadatos](xray-sdk-java-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.
Si tiene un gran número de clientes instrumentados en su código, un único segmento de solicitud puede contener muchos subsegmentos, uno por cada llamada realizada con un cliente instrumentado. Puede organizar y agrupar los subsegmentos incluyendo las llamadas del cliente en [subsegmentos personalizados](xray-sdk-java-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.
## Submódulos
Puede descargar el SDK de X-Ray para Java desde Maven. El SDK de X-Ray para Java está dividido en submódulos por caso de uso, con una factura de materiales para la administración de las versiones:
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-core/) (obligatorio): funcionalidad básica para la creación y transmisión de segmentos. Incluye `AWSXRayServletFilter` para instrumentar solicitudes entrantes.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk/)— Instrumenta las llamadas que Servicios de AWS se realizan con AWS SDK para Java los clientes añadiendo un cliente de rastreo como gestor de solicitudes.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2/)— Las llamadas de Instruments Servicios de AWS se realizan con clientes de la versión AWS SDK para Java 2.2 y versiones posteriores añadiendo un cliente de rastreo como interceptor de solicitudes.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-instrumentor/)— Con, instrumenta a `aws-xray-recorder-sdk-aws-sdk` todos los clientes automáticamente. AWS SDK para Java
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-aws-sdk-v2-instrumentor/)— Con`aws-xray-recorder-sdk-aws-sdk-v2`, instrumenta todos los clientes de AWS SDK para Java 2.2 y versiones posteriores de forma automática.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-apache-http/): instrumenta llamadas HTTP salientes realizadas con clientes Apache HTTP.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-spring/): proporciona interceptores para las aplicaciones del marco de trabajo Spring AOP.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-postgres/): instrumenta llamadas salientes a la base de datos PostgreSQL realizadas con JDBC.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-sql-mysql/): instrumenta llamadas salientes a la base de datos MySQL realizadas con JDBC.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-bom/): proporciona una lista de materiales que puede utilizar para especificar la versión que se debe utilizar en todos los submódulos.
+ [https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/](https://mvnrepository.com/artifact/com.amazonaws/aws-xray-recorder-sdk-metrics/)— Publica CloudWatch métricas de Amazon sin muestrear de tus segmentos de X-Ray recopilados.
Si utiliza Maven o Gradle para crear la aplicación, [añada el SDK de X-Ray para Java a la configuración de compilación](#xray-sdk-java-dependencies).
Para ver documentos de referencia sobre las clases y los métodos del SDK, consulte [Referencia de la API de AWS X-Ray SDK para Java](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc).
## Requisitos
El X-Ray SDK for Java requiere Java 8 o posterior, Servlet API 3, el AWS SDK y Jackson.
El SDK depende de las siguientes bibliotecas durante la compilación y el tiempo de ejecución:
+ AWS SDK para Java versión 1.11.398 o posterior
+ Servlet API 3.1.0
Estas dependencias se declaran en el archivo `pom.xml` del SDK y se incluyen de forma automática si realiza la compilación con Maven o Gradle.
Si utiliza una biblioteca que se incluye en el SDK de X-Ray para Java debe utilizar la versión que se incluye. Por ejemplo, si ya depende de Jackson durante el tiempo de ejecución e incluye archivos JAR en la implementación de esa dependencia, debe eliminar dichos archivos porque el archivo JAR del SDK incluye sus propias versiones de las bibliotecas Jackson.
## Administración de dependencias
El SDK de X-Ray para Java está disponible en Maven:
+ **Grupo**: `com.amazonaws`
+ **Artefacto**: `aws-xray-recorder-sdk-bom`
+ **Versión**: `2.11.0`
Si utiliza Maven para compilar la aplicación, añada el SDK como dependencia en su archivo `pom.xml`.
**Example pom.xml: dependencias**
```
com.amazonaws
aws-xray-recorder-sdk-bom
2.11.0
pom
import
com.amazonaws
aws-xray-recorder-sdk-core
com.amazonaws
aws-xray-recorder-sdk-apache-http
com.amazonaws
aws-xray-recorder-sdk-aws-sdk
com.amazonaws
aws-xray-recorder-sdk-aws-sdk-instrumentor
com.amazonaws
aws-xray-recorder-sdk-sql-postgres
com.amazonaws
aws-xray-recorder-sdk-sql-mysql
```
Si utiliza Gradle, añada el SDK como dependencia de tiempo de compilación en su archivo `build.gradle`.
**Example build.gradle: dependencias**
```
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile("org.springframework.boot:spring-boot-starter-test")
compile("com.amazonaws:aws-java-sdk-dynamodb")
compile("com.amazonaws:aws-xray-recorder-sdk-core")
compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk")
compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor")
compile("com.amazonaws:aws-xray-recorder-sdk-apache-http")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-postgres")
compile("com.amazonaws:aws-xray-recorder-sdk-sql-mysql")
testCompile("junit:junit:4.11")
}
dependencyManagement {
imports {
mavenBom('com.amazonaws:aws-java-sdk-bom:1.11.39')
mavenBom('com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0')
}
}
```
Si utiliza Elastic Beanstalk para implementar la aplicación, puede utilizar Maven o Gradle para compilar la aplicación en la instancia cada vez que realice la implementación, en lugar de compilar y cargar un archivo de gran tamaño que incluya todas sus dependencias. Consulte la [aplicación de ejemplo](xray-scorekeep.md) para ver un ejemplo en el que se utiliza Gradle.
# AWS X-Ray agente de autoinstrumentación para Java
**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 agente de AWS X-Ray autoinstrumentación para Java es una solución de rastreo que instrumenta sus aplicaciones web Java con un mínimo esfuerzo de desarrollo. El agente permite rastrear las aplicaciones basadas en servlets y todas las solicitudes posteriores del agente realizadas con marcos y bibliotecas compatibles. Entre ellas se incluyen las solicitudes HTTP a Apache, solicitudes mediante el SDK de AWS y consultas en SQL posteriores realizadas con un controlador JDBC. El agente propaga el contexto de X-Ray, incluidos todos los segmentos y subsegmentos activos, a través de subprocesos. Todas las configuraciones y la versatilidad del SDK de X-Ray siguen disponibles con el agente para Java. Se eligieron los valores predeterminados adecuados para garantizar que el agente funcione con el mínimo esfuerzo.
Lo más adecuado para la solución del agente de X-Ray son los servidores de aplicaciones web Java de solicitud-respuesta basados en servlets. Si su aplicación utiliza un marco asíncrono o no está bien diseñada como servicio de solicitud-respuesta, la instrumentación manual con el SDK podría ser más conveniente.
El agente X-Ray se crea con el kit de herramientas de comprensión de sistemas distribuidos, o Di. SCo Di SCo es un marco de código abierto para crear agentes Java que se pueden usar en sistemas distribuidos. Si bien no es necesario entender a Di SCo para usar el agente de rayos X, puede obtener más información sobre el proyecto visitando su [página de inicio en GitHub](https://github.com/awslabs/disco). El agente de X-Ray también es de código totalmente abierto. Para ver el código fuente, hacer contribuciones o plantear problemas sobre el agente, visita su [repositorio en GitHub](https://github.com/aws/aws-xray-java-agent).
## Aplicación de muestra
La aplicación [eb-java-scorekeep](https://github.com/aws-samples/eb-java-scorekeep/tree/xray-agent)de muestra está adaptada para ser instrumentada con el agente de rayos X. Esta ramificación no contiene ningún filtro de servlet ni configuración de grabadora, ya que estas funciones las realiza el agente. Para ejecutar la aplicación de forma local o utilizando recursos de AWS , siga los pasos indicados en el archivo readme de la aplicación de muestra. Las instrucciones para usar la aplicación de muestra con el fin de generar rastros de X-Ray se encuentran en el [tutorial de la aplicación de muestra](xray-scorekeep.md).
## Introducción
Para empezar a utilizar el agente de instrumentación automática de X-Ray para Java en su propia aplicación, siga estos pasos.
1. Ejecute el daemon de X-Ray en su entorno. Para obtener más información, consulte [AWS X-Ray demonio](xray-daemon.md).
1. Descargue la [última distribución del agente](https://github.com/aws/aws-xray-java-agent/releases/latest/download/xray-agent.zip). Descomprima el archivo y tome nota de su ubicación en el sistema de archivos. El contenido debe ser similar al siguiente.
```
disco
├── disco-java-agent.jar
└── disco-plugins
├── aws-xray-agent-plugin.jar
├── disco-java-agent-aws-plugin.jar
├── disco-java-agent-sql-plugin.jar
└── disco-java-agent-web-plugin.jar
```
1. Modifique los argumentos de JVM de su aplicación para incluir lo siguiente y así habilitar el agente. Asegúrese de que el argumento `-javaagent` esté colocado *delante* del argumento `-jar`, si procede. El proceso de modificación de los argumentos de JVM varía en función de las herramientas y los marcos que utilice para lanzar su servidor de Java. Consulte la documentación del marco de su servidor para obtener orientación específica.
```
-javaagent://disco-java-agent.jar=pluginPath=//disco-plugins
```
1. Para especificar cómo aparece el nombre de la aplicación en la consola de X-Ray, establezca la variable de entorno `AWS_XRAY_TRACING_NAME` o la propiedad de sistema `com.amazonaws.xray.strategy.tracingName`. Si no se proporciona un nombre, se utilizará un nombre predeterminado.
1. Reinicie el servidor o el contenedor. A partir de ese momento se rastrearán las solicitudes entrantes y sus llamadas posteriores. Si no ve los resultados esperados, consulte [Solución de problemas](#XRayAutoInstrumentationAgent-Troubleshooting).
## Configuración
El agente de X-Ray se configura mediante un archivo JSON externo proporcionado por el usuario. De forma predeterminada, este archivo se encuentra en la raíz de la ruta de clases del usuario denominada `xray-agent.json` (por ejemplo, en su directorio `resources`). Puede configurar una ubicación personalizada para el archivo de configuración estableciendo la propiedad de sistema `com.amazonaws.xray.configFile` en la ruta absoluta del sistema de archivos del archivo de configuración.
A continuación, se muestra un ejemplo de archivo de configuración.
```
{
"serviceName": "XRayInstrumentedService",
"contextMissingStrategy": "LOG_ERROR",
"daemonAddress": "127.0.0.1:2000",
"tracingEnabled": true,
"samplingStrategy": "CENTRAL",
"traceIdInjectionPrefix": "prefix",
"samplingRulesManifest": "/path/to/manifest",
"awsServiceHandlerManifest": "/path/to/manifest",
"awsSdkVersion": 2,
"maxStackTraceLength": 50,
"streamingThreshold": 100,
"traceIdInjection": true,
"pluginsEnabled": true,
"collectSqlQueries": false
}
```
### Especificación de la configuración
En la tabla siguiente se describen valores válidos para cada propiedad. Los nombres de las propiedades hay distinción entre mayúsculas y minúsculas, pero en sus claves no. En el caso de propiedades que las variables de entorno y las propiedades del sistema pueden anular, el orden de prioridad es siempre el siguiente: primero la variable de entorno, luego la propiedad del sistema y, por último, el archivo de configuración. Para obtener información sobre las propiedades que puede anular, consulte [Variables de entorno](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars). Todos los campos son opcionales.
| Nombre de la propiedad | Tipo | Valores válidos | Description (Descripción) | Variable de entorno | Propiedad del sistema | Predeterminado |
| --- | --- | --- | --- | --- | --- | --- |
| serviceName | Cadena | Cualquier cadena | El nombre del servicio instrumentado tal como aparecerá en la consola de X-Ray. | AWS\$1XRAY\$1TRACING\$1NAME | com.amazonaws.xray.strategy.tracingName | XRayInstrumentedService |
| contextMissingStrategy | Cadena | LOG\$1ERROR, IGNORE\$1ERROR | La acción que realiza el agente cuando intenta utilizar el contexto del segmento de X-Ray, pero no hay ninguno. | AWS\$1XRAYFALTA \$1CONTEXTO | com.amazonaws.xray.strategy. contextMissingStrategy | LOG\$1ERROR |
| daemonAddress | Cadena | Dirección IP y puerto formateados o lista de direcciones TCP y UDP | La dirección que utiliza el agente para comunicarse con el daemon de X-Ray. | AWS\$1XRAY\$1DAEMON\$1ADDRESS | com.amazonaws.xray.emitter.daemonAddress | 127.0.0.1:2000 |
| tracingEnabled | Booleano | True, False | Permite la instrumentación mediante el agente de X-Ray. | AWS\$1XRAY\$1TRACING\$1HABILITADO | com.amazonaws.xray.tracingEnabled | TRUE |
| samplingStrategy | Cadena | CENTRAL, LOCAL, NONE o ALL | La estrategia de muestreo que utiliza el agente. ALL captura todas las solicitudes, NONE no captura ninguna. Consulte [Reglas de muestreo](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sampling). | N/A | N/A | CENTRAL |
| traceIdInjectionPrefijo | Cadena | Cualquier cadena | Incluye el prefijo proporcionado antes de inyectar la traza IDs en los registros. | N/A | N/A | Ninguno (cadena vacía) |
| samplingRulesManifest | Cadena | Ruta de archivo absoluta | La ruta a un archivo de reglas de muestreo personalizadas que se utilizará como fuente de las reglas de muestreo para la estrategia de muestreo local o las reglas alternativas para la estrategia central. | N/A | N/A | [DefaultSamplingRules.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-core/src/main/resources/com/amazonaws/xray/strategy/sampling/DefaultSamplingRules.json) |
| awsServiceHandlerManifiesto | Cadena | Ruta de archivo absoluta | La ruta a una lista de parámetros permitidos personalizados que captura información adicional de los clientes del SDK de AWS . | N/A | N/A | [DefaultOperationParameterWhitelist.json](https://github.com/aws/aws-xray-sdk-java/blob/master/aws-xray-recorder-sdk-aws-sdk-v2/src/main/resources/com/amazonaws/xray/interceptors/DefaultOperationParameterWhitelist.json) |
| awsSdkVersion | Entero | 1, 2 | Versión del [SDK de AWS para Java](https://docs.aws.amazon.com/sdk-for-java/index.html) que está utilizando. Se ignora si no se establece también `awsServiceHandlerManifest`. | N/A | N/A | 2 |
| maxStackTraceLongitud | Entero | Enteros no negativos | El número máximo de líneas de un rastro de pila que se pueden registrar en una traza. | N/A | N/A | 50 |
| streamingThreshold | Entero | Enteros no negativos | Una vez cerrados al menos este número de subsegmentos, se transmiten al daemon out-of-band para evitar que los fragmentos sean demasiado grandes. | N/A | N/A | 100 |
| traceIdInjection | Booleano | True, False | Permite la inyección de los ID de rastro de X-Ray en los registros si también se agregan las dependencias y la configuración descritas en la [configuración de registro](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging). De lo contrario, no hace nada. | N/A | N/A | TRUE |
| pluginsEnabled | Booleano | True, False | Habilita los complementos que registran los metadatos sobre los AWS entornos en los que se opera. Consulte [Complementos de servicio](xray-sdk-java-configuration.md#xray-sdk-java-configuration-plugins). | N/A | N/A | TRUE |
| collectSqlQueries | Booleano | True, False | Registra cadenas de consultas SQL en subsegmentos SQL en la medida de lo posible. | N/A | N/A | FALSO |
| contextPropagation | Booleano | True, False | Propaga automáticamente el contexto de X-Ray entre subprocesos si es verdadero. De lo contrario, utiliza Thread Local para almacenar el contexto y se requiere la propagación manual de un subproceso a otro. | N/A | N/A | TRUE |
### Configuración de registro
El nivel de registro del agente de X-Ray se puede configurar de la misma manera que el SDK de X-Ray para Java. Consulte [Registro](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) para obtener más información sobre la configuración del registro con el SDK de X-Ray para Java.
### Instrumentación manual
Si desea realizar la instrumentación manual además de la instrumentación automática del agente, añada el SDK de X-Ray como una dependencia a su proyecto. Tenga en cuenta que los filtros de servlets personalizados del SDK que se mencionan en [Rastreo de solicitudes entrantes](xray-sdk-java-filters.md) no son compatibles con el agente de X-Ray.
**nota**
Debe usar la última versión del SDK de X-Ray para realizar la instrumentación manual y usar el agente al mismo tiempo.
Si está trabajando en un proyecto de Maven, añada las siguientes dependencias a su archivo `pom.xml`.
```
com.amazonaws
aws-xray-recorder-sdk-core
2.11.0
```
Si está trabajando en un proyecto de Gradle, añada las siguientes dependencias a su archivo `build.gradle`.
```
implementation 'com.amazonaws:aws-xray-recorder-sdk-core:2.11.0'
```
Puede añadir [subsegmentos personalizados](xray-sdk-java-subsegments.md) además de [anotaciones, metadatos y usuarios IDs](xray-sdk-java-segment.md) mientras usa el agente, tal como lo haría con el SDK normal. El agente propaga automáticamente el contexto de un subproceso a otro, por lo que no deberían hacer falta soluciones provisionales para propagar el contexto cuando se trabaja con aplicaciones multiproceso.
## Solución de problemas
Como el agente ofrece una instrumentación totalmente automática, puede resultar difícil identificar la causa raíz de un problema cuando se están produciendo problemas. Si el agente de X-Ray no funciona según lo esperado, revise los siguientes problemas y soluciones. El agente y el SDK de X-Ray utilizan Jakarta Commons Logging (JCL). Para ver el resultado del registro, asegúrese de que un puente que conecte JCL con su backend de registro esté en la ruta de clases, como en el siguiente ejemplo: `log4j-jcl` o `jcl-over-slf4j`.
### Problema: he habilitado el agente para Java en mi aplicación, pero no veo nada en la consola de X-Ray
**¿El daemon de X-Ray se está ejecutando en la misma máquina?**
Si no es así, consulte la [documentación del daemon de X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) para configurarlo.
**¿Ve un mensaje similar a “Iniciando la grabadora del agente de X-Ray” en los registros de su aplicación?**
Si ha agregado correctamente el agente a la aplicación, este mensaje estará registrado en el nivel INFO cuando se inicie la aplicación, antes de que esta comience a recibir solicitudes. Si este mensaje no aparece, significa que el agente para Java no se está ejecutando con el proceso de Java. Asegúrese de haber seguido todos los pasos de configuración correctamente sin errores tipográficos.
**En los registros de tu aplicación, ¿ves varios mensajes de error que digan algo así como «Suprimir la excepción por falta de AWS X-Ray contexto»?**
Estos errores se producen porque el agente está intentando instrumentar las solicitudes posteriores, como las solicitudes AWS del SDK o las consultas de SQL, pero no ha podido crear un segmento automáticamente. Si ve muchos de estos errores, es posible que el agente no sea la mejor herramienta para el uso que usted le quiere dar y, en su lugar, tal vez debería considerar la instrumentación manual con el SDK de X-Ray. Como alternativa, puede habilitar los [registros de depuración](xray-sdk-java-configuration.md#xray-sdk-java-configuration-logging) del SDK de X-Ray para ver el rastro de pila del punto donde se producen las excepciones de falta de contexto. Puede agrupar estas porciones del código con segmentos personalizados, lo que debería corregir estos errores. Para ver un ejemplo de cómo encapsular las solicitudes posteriores con segmentos personalizados, consulte el código de muestra que aparece en [Instrumentación de código de inicio](scorekeep-startup.md).
### Problema: algunos de los segmentos que espero no aparecen en la consola de X-Ray
**¿Su aplicación utiliza el multiproceso?**
Si espera que se creen ciertos segmentos pero no aparecen en la consola, la causa pueden ser subprocesos en segundo plano en la aplicación. Si su aplicación realiza tareas mediante subprocesos en segundo plano que son «activarlos y olvidarlos», como realizar una llamada puntual a una función de Lambda con AWS el SDK o sondear periódicamente algún punto final HTTP, esto puede confundir al agente mientras propaga el contexto entre los subprocesos. Para comprobar que este es su problema, habilite los registros de depuración del SDK de X-Ray y mire a ver si hay mensajes como este: *Not emitting segment named as it parents in-progress subsegments*. Para solucionar este problema, puede intentar unir los subprocesos en segundo plano antes de que el servidor vuelva a funcionar para asegurarse de que todo el trabajo realizado en ellos queda registrado. O bien, puede establecer la configuración `contextPropagation` del agente en `false` para inhabilitar la propagación del contexto en subprocesos en segundo plano. En ese caso, tendrá que instrumentar manualmente esos subprocesos con segmentos personalizados o ignorar las excepciones de falta de contexto que generen.
**¿Ha establecido reglas de muestreo?**
Si aparecen segmentos aparentemente aleatorios o inesperados en la consola de X-Ray, o los segmentos que esperaba que estuvieran en la consola no están, es posible que tenga un problema de muestreo. El agente de X-Ray lleva a cabo un muestreo centralizado en todos los segmentos que crea, aplicando las reglas de la consola de X-Ray. La regla por defecto es obtener muestras en 1 segmento por segundo y, posteriormente, en el 5 % de los segmentos. Eso significa que es posible que no se obtengan muestras de los segmentos que se creen rápidamente con el agente. Para solucionar este problema, debe crear reglas de muestreo personalizadas en la consola de X-Ray para un muestreo adecuado de los segmentos deseados. Para obtener más información, consulte [Configuración de reglas de muestreo](xray-console-sampling.md).
# Configuración del SDK de X-Ray para Java
**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 Java incluye una clase denominada `AWSXRay` que proporciona la grabadora global. Esto es un `TracingHandler` que puede utilizar para instrumentar su código. Puede configurar la grabadora global para que personalice el `AWSXRayServletFilter` que crea los segmentos para las llamadas HTTP entrantes.
**Topics**
+ [Complementos del servicio](#xray-sdk-java-configuration-plugins)
+ [Reglas de muestreo](#xray-sdk-java-configuration-sampling)
+ [Registro](#xray-sdk-java-configuration-logging)
+ [Agentes de escucha de segmento](#xray-sdk-java-configuration-listeners)
+ [Variables de entorno](#xray-sdk-java-configuration-envvars)
+ [Propiedades del sistema](#xray-sdk-java-configuration-sysprops)
## Complementos del servicio
Utilice `plugins` para registrar información sobre el servicio que aloja la aplicación.
**Plugins**
+ Amazon EC2: `EC2Plugin` agrega el ID de la instancia, la zona de disponibilidad y el grupo de CloudWatch registros.
+ Elastic Beanstalk: `ElasticBeanstalkPlugin` añade el nombre de entorno, la etiqueta de versión y el ID de implementación.
+ Amazon ECS: `ECSPlugin` agrega el ID de contenedor.
+ Amazon EKS: `EKSPlugin` añade el ID del contenedor, el nombre del clúster, el ID del pod y el grupo de CloudWatch registros.
![\[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.png)
Para utilizar un complemento, llame a `withPlugin` en su `AWSXRayRecorderBuilder`.
**Example src/main/java/scorekeep/WebConfig.java: grabadora**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.plugins.ElasticBeanstalkPlugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/ElasticBeanstalkPlugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ElasticBeanstalkPlugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
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.
Sí AWS Lambda, no puedes modificar la frecuencia de muestreo. Si un servicio instrumentado llama a su función, Lambda registrará las llamadas que generaron solicitudes muestreadas por ese servicio. Si el rastreo activo está activado y no hay ningún encabezado de rastreo, Lambda toma la decisión de muestreo.
Para proporcionar reglas de copia de seguridad en Spring, configure la grabadora global con una `CentralizedSamplingStrategy` en una clase de configuración:
**Example src/main/java/myapp/WebConfig.java: configuración de la grabadora**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
@Configuration
public class WebConfig {
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
```
Para Tomcat, añada un agente de escucha que amplíe `ServletContextListener` y registre el agente de escucha en el descriptor de la implementación.
**Example src/com/myapp/web/Startup.java**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.AWSXRayRecorderBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorderBuilder.html);
import [com.amazonaws.xray.plugins.EC2Plugin](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/plugins/EC2Plugin.html);
import [com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/sampling/LocalizedSamplingStrategy.html);
import java.net.URL;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;
public class Startup implements ServletContextListener {
@Override
public void contextInitialized(ServletContextEvent event) {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new EC2Plugin());
URL ruleFile = Startup.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new CentralizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
@Override
public void contextDestroyed(ServletContextEvent event) { }
}
```
**Example WEB-INF/web.xml**
```
...
com.myapp.web.Startup
```
Para utilizar reglas locales solo, reemplace la `CentralizedSamplingStrategy` por `LocalizedSamplingStrategy`.
```
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
```
## Registro
De forma predeterminada, el SDK envía mensajes de nivel de `ERROR` a los registros de la aplicación. Puede habilitar el registro a nivel de depuración en el SDK para enviar registros más detallados al archivo de registro de la aplicación. Los niveles de registro válidos son `DEBUG`, `INFO`, `WARN`, `ERROR` y `FATAL`. El nivel de registro `FATAL` silencia todos los mensajes de registro porque el SDK no registra un nivel fatal.
**Example application.properties**
Configure el nivel de registro con la propiedad `logging.level.com.amazonaws.xray`.
```
logging.level.com.amazonaws.xray = DEBUG
```
Utilice registros de depuración para identificar problemas como la presencia de subsegmentos sin cerrar al [generar subsegmentos de forma manual](xray-sdk-java-subsegments.md).
### Inyección de ID de registro de seguimiento en los registros
Para exponer el ID de seguimiento completo actual en las instrucciones del registro, puede incluir el ID en el contexto de diagnóstico asignado (MDC). Mediante la interfaz `SegmentListener`, se llama a los métodos desde la grabadora de X-Ray durante los eventos del ciclo de vida del segmento. Cuando comienza un segmento o subsegmento, el ID de seguimiento completo se incluye en el MDC con la clave `AWS-XRAY-TRACE-ID`. Cuando termina ese segmento, se elimina la clave del MDC. Esto expone el ID de registro de seguimiento a la biblioteca de registro en uso. Cuando termina un subsegmento, su ID principal se incluye en el MDC.
**Example ID de seguimiento completo**
El ID completo se representa como `TraceID@EntityID`
```
1-5df42873-011e96598b447dfca814c156@541b3365be3dafc3
```
Esta función funciona con aplicaciones Java equipadas con el SDK de AWS X-Ray para Java y admite las siguientes configuraciones de registro:
+ SLF4API de interfaz J con backend Logback
+ SLF4API de front-end J con el backend Log4J2
+ API front-end Log4J2 con backend Log4J2
Consulte las siguientes pestañas para conocer las necesidades de cada front end y backend.
------
#### [ SLF4J Frontend ]
1. Agregue la siguiente dependencia de Maven a su proyecto.
```
com.amazonaws
aws-xray-recorder-sdk-slf4j
2.11.0
```
1. Incluya el método `withSegmentListener` al construir la `AWSXRayRecorder`. Esto agrega una `SegmentListener` clase, que inyecta automáticamente una nueva traza en el J MDC. IDs SLF4
`SegmentListener` toma una cadena opcional como parámetro para configurar el prefijo de la instrucción de registro. El prefijo se puede configurar de las siguientes maneras:
+ **Ninguno**: utiliza el prefijo predeterminado `AWS-XRAY-TRACE-ID`.
+ **Vacío**: utiliza una cadena vacía (por ejemplo, `""`).
+ **Personalizado**: utiliza un prefijo personalizado tal como se define en la cadena.
**Example `AWSXRayRecorderBuilder` instrucción**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new SLF4JSegmentListener("CUSTOM-PREFIX"));
```
------
#### [ Log4J2 front end ]
1. Agregue la siguiente dependencia de Maven a su proyecto.
```
com.amazonaws
aws-xray-recorder-sdk-log4j
2.11.0
```
1. Incluya el método `withSegmentListener` al construir la `AWSXRayRecorder`. Esto añadirá una `SegmentListener` clase, que inyectará automáticamente una nueva traza totalmente cualificada IDs en el SLF4 J MDC.
`SegmentListener` toma una cadena opcional como parámetro para configurar el prefijo de la instrucción de registro. El prefijo se puede configurar de las siguientes maneras:
+ **Ninguno**: utiliza el prefijo predeterminado `AWS-XRAY-TRACE-ID`.
+ **Vacío**: utiliza una cadena vacía (por ejemplo, `""`) y elimina el prefijo.
+ **Personalizado**: utiliza el prefijo personalizado definido en la cadena.
**Example `AWSXRayRecorderBuilder` instrucción**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new Log4JSegmentListener("CUSTOM-PREFIX"));
```
------
#### [ Logback backend ]
Para insertar el ID de registro de seguimiento en los eventos de registro, debe modificar el `PatternLayout` del registrador, que da formato a cada instrucción de registro.
1. Busque dónde está configurado el `patternLayout`. Puede hacerlo mediante programación o a través de un archivo de configuración XML. Para obtener más información, consulte [Configuración de Logback](http://logback.qos.ch/manual/configuration.html).
1. Inserte `%X{AWS-XRAY-TRACE-ID}` en cualquier lugar del `patternLayout` para insertar el ID de rastro en las futuras instrucciones de registro. `%X{}` indica que recupera un valor con la clave proporcionada del MDC. Para obtener más información sobre PatternLayouts Logback, consulte. [PatternLayout](https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout)
------
#### [ Log4J2 backend ]
1. Busque dónde está configurado el `patternLayout`. Puede hacerlo mediante programación o a través de un archivo de configuración escrito en XML, JSON, YAML o con las propiedades del formato.
Para obtener más información sobre la configuración de Log4J2 ´mediante un archivo de configuración, consulte [Configuración](https://logging.apache.org/log4j/2.x/manual/configuration.html).
Para obtener más información sobre la configuración de Log4J2 mediante programación, consulte [Configuración programática](https://logging.apache.org/log4j/2.x/manual/customconfig.html).
1. Inserte `%X{AWS-XRAY-TRACE-ID}` en cualquier lugar del `PatternLayout` para insertar el ID de rastro en las futuras instrucciones de registro. `%X{}` indica que recupera un valor con la clave proporcionada del MDC. [Para obtener más información sobre PatternLayouts Log4J2, consulte Diseño de patrones.](https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout)
------
**Ejemplo de inyección de ID de registro de seguimiento**
A continuación se muestra una cadena de `PatternLayout` modificada para incluir el ID de registro de seguimiento. El ID de registro de seguimiento se imprime después del nombre del subproceso (`%t`) y antes del nivel de registro (`%-5p`).
**Example `PatternLayout` Con inyección de ID**
```
%d{HH:mm:ss.SSS} [%t] %X{AWS-XRAY-TRACE-ID} %-5p %m%n
```
AWS X-Ray imprime automáticamente la clave y el ID de rastreo en la declaración de registro para facilitar el análisis. A continuación se muestra una instrucción de registro que utiliza el `PatternLayout` modificado.
**Example Instrucción de registro con inyección de ID**
```
2019-09-10 18:58:30.844 [nio-5000-exec-4] AWS-XRAY-TRACE-ID: 1-5d77f256-19f12e4eaa02e3f76c78f46a@1ce7df03252d99e1 WARN 1 - Your logging message here
```
El mensaje de registro en sí está alojado en el patrón `%m` y se establece al llamar al registrador.
## Agentes de escucha de segmento
Los agentes de escucha de segmento son una interfaz para interceptar eventos del ciclo de vida, como el comienzo y el final de segmentos producidos por `AWSXRayRecorder`. La implementación de una función de evento de un oyente de segmento es posible que sea agregar la misma anotación a todos los subsegmentos cuando se crean con [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-), registrar un mensaje después de que cada segmento se envíe al daemon mediante [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-) o registrar consultas enviadas por los interceptores de SQL mediante [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#beforeEndSubsegment-com.amazonaws.xray.entities.Subsegment-) para verificar si el subsegmento representa una consulta SQL, agregando metadatos adicionales si es así.
Para consultar la lista completa de funciones de `SegmentListener`, consulte la documentación del [SDK de grabación de AWS X-Ray para la API de Java](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html).
En el ejemplo siguiente se muestra cómo agregar una anotación coherente a todos los subsegmentos al crear con [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#onBeginSubsegment-com.amazonaws.xray.entities.Subsegment-) e imprimir un mensaje de registro al final de cada segmento con [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/listeners/SegmentListener.html#afterEndSegment-com.amazonaws.xray.entities.Segment-).
**Example MySegmentListener.java**
```
import com.amazonaws.xray.entities.Segment;
import com.amazonaws.xray.entities.Subsegment;
import com.amazonaws.xray.listeners.SegmentListener;
public class MySegmentListener implements SegmentListener {
.....
@Override
public void onBeginSubsegment(Subsegment subsegment) {
subsegment.putAnnotation("annotationKey", "annotationValue");
}
@Override
public void afterEndSegment(Segment segment) {
// Be mindful not to mutate the segment
logger.info("Segment with ID " + segment.getId());
}
}
```
A continuación, se hace referencia a este agente de escucha de segmento personalizado cuando se crea `AWSXRayRecorder`.
**Example AWSXRayRecorderBuilder declaración**
```
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard().withSegmentListener(new MySegmentListener());
```
## Variables de entorno
Puede usar variables de entorno para configurar el SDK de X-Ray para Java. El SDK admite las siguientes variables.
+ `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.
+ `AWS_XRAY_DAEMON_ADDRESS`: establezca el host y el puerto del oyente del daemon de X-Ray. De forma predeterminada, el SDK utiliza `127.0.0.1:2000` tanto para los datos de rastro (UDP) como para el muestreo (TCP). 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.
**Formato**
+ **El mismo puerto**: `address:port`
+ **Puertos diferentes**: `tcp:address:port udp:address:port`
+ `AWS_LOG_GROUP`: establece el nombre de un grupo de registro en el grupo de registro asociado a su aplicación. Si su grupo de registros usa la misma AWS cuenta y región que su aplicación, X-Ray buscará automáticamente los datos de los segmentos de su aplicación utilizando este grupo de registros especificado. Para obtener información general acerca de los grupos de registro, consulte [Trabajar con grupos de registros y flujos de registros](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).
+ `AWS_XRAY_TRACING_NAME`: establezca el 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-java-filters.md#xray-sdk-java-filters-naming) del filtro de servlet.
Las variables de entorno anulan las [propiedades de sistema](#xray-sdk-java-configuration-sysprops) equivalentes y los valores establecidos en el código.
## Propiedades del sistema
Puede utilizar las propiedades del sistema como una alternativa específica de JVM para las [variables de entorno](#xray-sdk-java-configuration-envvars). El SDK admite las propiedades siguientes:
+ `com.amazonaws.xray.strategy.tracingName`: equivalente a `AWS_XRAY_TRACING_NAME`.
+ `com.amazonaws.xray.emitters.daemonAddress`: equivalente a `AWS_XRAY_DAEMON_ADDRESS`.
+ `com.amazonaws.xray.strategy.contextMissingStrategy`: equivalente a `AWS_XRAY_CONTEXT_MISSING`.
Si se ha establecido tanto una propiedad del sistema y como su variable de entorno equivalente, se utiliza el valor de la variable de entorno. En cualquier caso, esos valores anulan los valores establecidos en el código.
# Rastreo de las solicitudes entrantes con el SDK de X-Ray para Java
**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.
Utilice un `Filter` para instrumentar las solicitudes HTTP entrantes. Cuando añade el filtro de servlet de X-Ray a su aplicación, el SDK de X-Ray para Java crea un segmento para cada solicitud muestreada. Este segmento incluye el momento, el método y la disposición de la solicitud HTTP. La instrumentación adicional crea subsegmentos en este segmento.
**nota**
En el AWS Lambda caso de las funciones, Lambda crea un segmento para cada solicitud muestreada. Para obtener más información, consulte [AWS Lambda y AWS X-Ray](xray-services-lambda.md).
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 controlador de mensajes 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.
**Topics**
+ [Agregar un filtro de seguimiento a la aplicación (Tomcat)](#xray-sdk-java-filters-tomcat)
+ [Agregar un filtro de seguimiento a la aplicación (Spring)](#xray-sdk-java-filters-spring)
+ [Configuración de una estrategia de nomenclatura de segmentos](#xray-sdk-java-filters-naming)
## Agregar un filtro de seguimiento a la aplicación (Tomcat)
Para Tomcat, añada un `` al archivo `web.xml` de su proyecto. Use el parámetro `fixedName` para especificar un [nombre de servicio](#xray-sdk-java-filters-naming) que se aplique a los segmentos creados para las solicitudes entrantes.
**Example WEB-INF/web.xml - Tomcat**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
fixedName
MyApp
AWSXRayServletFilter
*
```
## Agregar un filtro de seguimiento a la aplicación (Spring)
Para Spring, añada un `Filter` a la clase `WebConfig`. Pase el nombre del segmento al constructor [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) como cadena.
**Example src/main/java/myapp/WebConfig.java: primavera**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
}
```
## 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.
Para utilizar el mismo nombre para todos los segmentos de solicitud, especifique el nombre de la aplicación cuando inicie el filtro de servlet, tal y como se muestra en [la sección anterior](#xray-sdk-java-filters-tomcat). Esto tiene el mismo efecto que crear un fijo [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)llamándolo `SegmentNamingStrategy.fixed()` y pasándolo al [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html)constructor.
**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-java-configuration.md#xray-sdk-java-configuration-envvars).
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 nombres de forma dinámica en Tomcat, utilice `dynamicNamingRecognizedHosts` y `dynamicNamingFallbackName` para definir el patrón y el nombre predeterminado, respectivamente.
**Example WEB-INF/web.xml: filtro de servlet con nomenclatura dinámica**
```
AWSXRayServletFilter
com.amazonaws.xray.javax.servlet.AWSXRayServletFilter
dynamicNamingRecognizedHosts
*.example.com
dynamicNamingFallbackName
MyApp
AWSXRayServletFilter
*
```
En el caso de Spring, crea una dinámica [SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html)mediante una llamada `SegmentNamingStrategy.dynamic()` y pásala al `AWSXRayServletFilter` constructor.
**Example src/main/java/myapp/WebConfig.java: filtro de servlets con nomenclatura dinámica**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
import [com.amazonaws.xray.strategy.SegmentNamingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/SegmentNamingStrategy.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("MyApp", "*.example.com"));
}
}
```
# Rastreo de llamadas al AWS SDK con el X-Ray SDK for Java
**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 la aplicación realiza llamadas Servicios de AWS para almacenar datos, escribir en una cola o enviar notificaciones, el X-Ray SDK for Java rastrea las llamadas en sentido descendente en subsegmentos.](xray-sdk-java-subsegments.md) Los recursos y Servicios de AWS rastreados a los que accede dentro de dichos servicios (por ejemplo, un bucket de Amazon S3 o una cola de Amazon SQS) aparecerán como nodos posteriores en el mapa de rastros en la consola de X-Ray.
El SDK de X-Ray para Java instrumenta automáticamente todos los clientes del SDK de AWS cuando usted incluye el `aws-sdk` y un [submódulo](xray-sdk-java.md#xray-sdk-java-submodules) `aws-sdk-instrumentor` en su compilación. Si no incluye el submódulo Instrumentor, puede elegir instrumentar ciertos clientes a la vez que omite otros.
Para instrumentar clientes individuales, elimina el `aws-sdk-instrumentor` submódulo de la compilación y añade uno `XRayClient` como a tu cliente del AWS SDK mediante `TracingHandler` el generador de clientes del servicio.
Por ejemplo, para instrumentar un cliente `AmazonDynamoDB`, transfiera un controlador de rastros a `AmazonDynamoDBClientBuilder`.
**Example MyModel.java: cliente de DynamoDB**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html);
...
public class MyModel {
private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
.withRegion(Regions.fromName(System.getenv("AWS_REGION")))
.withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
.build();
...
```
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
Para instrumentar las llamadas posteriores a la versión Servicios de AWS AWS SDK para Java 2.2 y versiones posteriores, puede omitir el `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` módulo de la configuración de compilación. Incluya `aws-xray-recorder-sdk-aws-sdk-v2 module` en su lugar y después instrumente los clientes por separado configurándolos con `TracingInterceptor`.
**Example AWS SDK para Java 2.2 y versiones posteriores: interceptor de rastreo**
```
import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...
public class MyModel {
private DynamoDbClient client = DynamoDbClient.builder()
.region(Region.US_WEST_2)
.overrideConfiguration(ClientOverrideConfiguration.builder()
.addExecutionInterceptor(new TracingInterceptor())
.build()
)
.build();
//...
```
# Rastreo de llamadas a servicios web HTTP posteriores con el SDK de X-Ray para Java
**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 a microservicios o a HTTP públicos APIs, puedes usar la versión del SDK de X-Ray para Java `HttpClient` para instrumentar esas llamadas y añadir la API al gráfico del servicio como un servicio descendente.
El SDK de X-Ray para Java incluye `DefaultHttpClient` `HttpClientBuilder` clases que se pueden usar en lugar de HttpComponents los equivalentes de Apache para instrumentar las llamadas HTTP salientes.
+ `com.amazonaws.xray.proxies.apache.http.DefaultHttpClient` - `org.apache.http.impl.client.DefaultHttpClient`
+ `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` - `org.apache.http.impl.client.HttpClientBuilder`
Estas bibliotecas se encuentran en el submódulo [`aws-xray-recorder-sdk-apache-http`](xray-sdk-java.md).
Puede sustituir las instrucciones actuales de importación con el equivalente a X-Ray para instrumentar todos los clientes, o bien utilizar el nombre completo cuando inicie un cliente para instrumentar clientes específicos.
**Example HttpClientBuilder**
```
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.util.EntityUtils;
import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html);
...
public String randomName() throws IOException {
CloseableHttpClient httpclient = HttpClientBuilder.create().build();
HttpGet httpGet = new HttpGet("http://names.example.com/api/");
CloseableHttpResponse response = httpclient.execute(httpGet);
try {
HttpEntity entity = response.getEntity();
InputStream inputStream = entity.getContent();
ObjectMapper mapper = new ObjectMapper();
Map jsonMap = mapper.readValue(inputStream, Map.class);
String name = jsonMap.get("name");
EntityUtils.consume(entity);
return name;
} finally {
response.close();
}
}
```
Cuando se instrumenta una llamada a una API web posterior, el del SDK de X-Ray para Java registra un subsegmento con información sobre la solicitud HTTP y la respuesta. X-Ray utiliza el subsegmento para generar un segmento inferido de la API remota.
**Example Subsegmento para una llamada HTTP posterior**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example Segmento inferido para una llamada HTTP posterior**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
# Rastreo de consultas SQL con el SDK de X-Ray para Java
**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
## Interceptores SQL
Instrumente consultas de base de datos SQL añadiendo el interceptor JDBC del SDK de X-Ray para Java a la configuración del origen de datos.
+ **PostgreSQL** – `com.amazonaws.xray.sql.postgres.TracingInterceptor`
+ **MySQL** – `com.amazonaws.xray.sql.mysql.TracingInterceptor`
Estos interceptadores están en los [submódulos `aws-xray-recorder-sql-postgres` y `aws-xray-recorder-sql-mysql`](xray-sdk-java.md), respectivamente. Implementan `org.apache.tomcat.jdbc.pool.JdbcInterceptor` y son compatibles con grupos de conexión Tomcat.
**nota**
Los interceptores de SQL no registran la consulta SQL en subsegmentos por motivos de seguridad.
Para Spring, añada el interceptor a un archivo de propiedades y cree el origen de datos con `DataSourceBuilder` de Spring Boot.
**Example `src/main/java/resources/application.properties`: interceptor JDBC de PostgreSQL**
```
spring.datasource.continue-on-error=true
spring.jpa.show-sql=false
spring.jpa.hibernate.ddl-auto=create-drop
spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect
```
**Example `src/main/java/myapp/WebConfig.java`: origen de datos**
```
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.jdbc.DataSourceBuilder;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import javax.servlet.Filter;
import javax.sql.DataSource;
import java.net.URL;
@Configuration
@EnableAutoConfiguration
@EnableJpaRepositories("myapp")
public class RdsWebConfig {
@Bean
@ConfigurationProperties(prefix = "spring.datasource")
public DataSource dataSource() {
logger.info("Initializing PostgreSQL datasource");
return DataSourceBuilder.create()
.driverClassName("org.postgresql.Driver")
.url("jdbc:postgresql://" + System.getenv("RDS_HOSTNAME") + ":" + System.getenv("RDS_PORT") + "/ebdb")
.username(System.getenv("RDS_USERNAME"))
.password(System.getenv("RDS_PASSWORD"))
.build();
}
...
}
```
Para Tomcat, llame a `setJdbcInterceptors` en el origen de datos JDBC con una referencia a la clase del SDK de X-Ray para Java.
**Example `src/main/myapp/model.java`: origen de datos**
```
import org.apache.tomcat.jdbc.pool.DataSource;
...
DataSource source = new DataSource();
source.setUrl(url);
source.setUsername(user);
source.setPassword(password);
source.setDriverClassName("com.mysql.jdbc.Driver");
source.setJdbcInterceptors("com.amazonaws.xray.sql.mysql.TracingInterceptor;");
```
El SDK de X-Ray para Java incluye la biblioteca de origen de datos JDBC Tomcat, pero puede declararla como una dependencia para documentar su uso.
**Example `pom.xml`: origen de datos JDBC**
```
org.apache.tomcat
tomcat-jdbc
8.0.36
provided
```
## Decorador de rastreo SQL nativo
+ Añada [https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql](https://github.com/aws/aws-xray-sdk-java/tree/master/aws-xray-recorder-sdk-sql) a sus dependencias.
+ Decore el origen de datos, conexión o declaración de su base de datos.
```
dataSource = TracingDataSource.decorate(dataSource)
connection = TracingConnection.decorate(connection)
statement = TracingStatement.decorateStatement(statement)
preparedStatement = TracingStatement.decoratePreparedStatement(preparedStatement, sql)
callableStatement = TracingStatement.decorateCallableStatement(callableStatement, sql)
```
# Generación de subsegmentos personalizados con el SDK de X-Ray para Java
**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 `beginSubsegment` y `endSubsegment`.
**Example GameModel.java: subsegmento personalizado**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
...
public void saveGame(Game game) throws SessionNotFoundException {
// wrap in subsegment
Subsegment subsegment = AWSXRay.beginSubsegment("Save Game");
try {
// check session
String sessionId = game.getSession();
if (sessionModel.loadSession(sessionId) == null ) {
throw new SessionNotFoundException(sessionId);
}
mapper.save(game);
} catch (Exception e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment();
}
}
```
En este ejemplo, el código del subsegmento carga la sesión del juego desde DynamoDB con un método del modelo de sesión y utiliza el mapeador de DynamoDB para AWS SDK para Java guardar la partida. Cuando se encapsula este código en un subsegmento, las llamadas a DynamoDB se convierten en elementos secundarios del subsegmento `Save Game` en la vista de rastros en la consola.
![\[Timeline showing Scorekeep and DynamoDB operations with durations and status checks.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png)
Si en el código en su subsegmentos aparecen excepciones comprobadas, envuélvalo en un bloque `try` y llame a `AWSXRay.endSubsegment()` en un bloque `finally` para garantizar que el subsegmento está siempre cerrado. Si un subsegmento no está cerrado, el segmento primario no se puede completar y no se envía a X-Ray.
En los códigos donde no aparecen excepciones comprobadas, puede transferir el código a `AWSXRay.CreateSubsegment` como una función de Lambda.
**Example Función Lambda de subsegmento**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
AWSXRay.createSubsegment("getMovies", (subsegment) -> {
// function code
});
```
Cuando crea un subsegmento dentro de un segmento o de otro subsegmento, el SDK de X-Ray para Java 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"
}
},
```
Para la programación asíncrona y multiproceso, debe pasar manualmente el subsegmento al método `endSubsegment()` para asegurarse de que se cierra correctamente, ya que el contexto de X-Ray puede modificarse durante la ejecución asíncrona. Si un subsegmento asíncrono se cierra después de cerrar su segmento principal, este método transmitirá automáticamente todo el segmento al daemon de X-Ray.
**Example Subsegmento asíncrono**
```
@GetMapping("/api")
public ResponseEntity api() {
CompletableFuture.runAsync(() -> {
Subsegment subsegment = AWSXRay.beginSubsegment("Async Work");
try {
Thread.sleep(3000);
} catch (InterruptedException e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment(subsegment);
}
});
return ResponseEntity.ok().build();
}
```
# Adición de anotaciones y metadatos a los segmentos con el SDK de X-Ray para Java
**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-java-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 Java](#xray-sdk-java-segment-annotations)
+ [Registro de metadatos con el SDK de X-Ray para Java](#xray-sdk-java-segment-metadata)
+ [Grabación del usuario IDs con el SDK de X-Ray para Java](#xray-sdk-java-segment-userid)
## Registro de anotaciones con el SDK de X-Ray para Java
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 `AWSXRay`.
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
...
Segment document = AWSXRay.getCurrentSegment();
```
o
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
Subsegment document = AWSXRay.getCurrentSubsegment();
```
1. Llame a `putAnnotation` con una clave de cadena y un valor booleano, numérico o de cadena.
```
document.putAnnotation("mykey", "my value");
```
El siguiente ejemplo muestra cómo llamar a `putAnnotation` con una clave de cadena que incluye un punto y un valor booleano, numérico o de cadena.
```
document.putAnnotation("testkey.test", "my value");
```
El SDK registra las anotaciones como pares de clave-valor en un objeto `annotations` del documento de segmento. Si llama dos veces a `putAnnotation` 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).
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java): anotaciones y metadatos**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
public void saveGame(Game game) throws SessionNotFoundException {
// wrap in subsegment
Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
try {
// check session
String sessionId = game.getSession();
if (sessionModel.loadSession(sessionId) == null ) {
throw new SessionNotFoundException(sessionId);
}
Segment segment = AWSXRay.getCurrentSegment();
subsegment.putMetadata("resources", "game", game);
segment.putAnnotation("gameid", game.getId());
mapper.save(game);
} catch (Exception e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment();
}
}
```
## Registro de metadatos con el SDK de X-Ray para Java
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 `AWSXRay`.
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
...
Segment document = AWSXRay.getCurrentSegment();
```
o
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
Subsegment document = AWSXRay.getCurrentSubsegment();
```
1. Llame a `putMetadata` con un espacio de nombres de cadena, una clave de cadena y un valor booleano, numérico, de cadena o de objeto.
```
document.putMetadata("my namespace", "my key", "my value");
```
o
Llame a `putMetadata` con solo una clave y un valor.
```
document.putMetadata("my key", "my value");
```
Si no especifica un espacio de nombres, el SDK utiliza `default`. Si llama dos veces a `putMetadata` con la misma clave, se sobrescriben los valores previamente registrados en ese segmento o subsegmento.
**Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java): anotaciones y metadatos**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html);
...
public void saveGame(Game game) throws SessionNotFoundException {
// wrap in subsegment
Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame");
try {
// check session
String sessionId = game.getSession();
if (sessionModel.loadSession(sessionId) == null ) {
throw new SessionNotFoundException(sessionId);
}
Segment segment = AWSXRay.getCurrentSegment();
subsegment.putMetadata("resources", "game", game);
segment.putAnnotation("gameid", game.getId());
mapper.save(game);
} catch (Exception e) {
subsegment.addException(e);
throw e;
} finally {
AWSXRay.endSubsegment();
}
}
```
## Grabación del usuario IDs con el SDK de X-Ray para Java
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 `AWSXRay`.
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html);
...
Segment document = AWSXRay.getCurrentSegment();
```
1. Llame a `setUser` con un ID de cadena del usuario que envió la solicitud.
```
document.setUser("U12345");
```
Puede llamar a `setUser` en sus controladores para registrar el ID de usuario en cuanto la aplicación empiece a procesar la solicitud. Si solo va a utilizar el segmento para establecer el ID de usuario, puede encadenar las llamadas en una sola línea.
**Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java): ID de usuario**
```
import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html);
...
@RequestMapping(value="/{userId}", method=RequestMethod.POST)
public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException {
AWSXRay.getCurrentSegment().setUser(userId);
return moveFactory.newMove(sessionId, gameId, userId, move);
}
```
Para buscar rastros de un ID de usuario, utilice la palabra clave `user` en una [expresión de filtro](xray-console-filters.md).
## AWS X-Ray métricas del X-Ray SDK para Java
**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
En este tema se describen el espacio de AWS X-Ray nombres, las métricas y las dimensiones. Puedes usar el SDK de X-Ray para Java para publicar CloudWatch métricas de Amazon sin muestrear de los segmentos de X-Ray recopilados. Estas métricas se derivan de la horade inicio y finalización del segmento, y los marcadores de estado limitado, fallo y error. Utilice estas métricas de seguimiento para exponer los reintentos y los problemas de dependencia con los subsegmentos.
CloudWatch es un repositorio de métricas. Una métrica es el concepto fundamental CloudWatch y representa un conjunto de puntos de datos ordenados en el tiempo. Usted (o Servicios de AWS) publica puntos de datos de métricas CloudWatch y recupera las estadísticas sobre esos puntos de datos como un conjunto ordenado de datos de series temporales.
Las métricas se definen de forma exclusiva mediante un nombre, un espacio de nombres y una o varias dimensiones. Cada punto de datos tiene una marca temporal y, opcionalmente, una unidad de medida. Cuando se solicitan estadísticas, el flujo de datos devuelto se identifica mediante el espacio de nombres, el nombre de la métrica y la dimensión.
Para obtener más información al respecto CloudWatch, consulta la [https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/).
### CloudWatch Métricas de X-Ray
El espacio de nombres de `ServiceMetrics/SDK` incluye las siguientes métricas.
| Métrica | Estadísticas disponibles | Description (Descripción) | Unidades |
| --- | --- | --- | --- |
| `Latency` | Media, mínima, máxima, recuento | La diferencia entre la hora de inicio y finalización. Media, mínima y máxima describen la latencia operativa. Recuento describe el recuento de llamadas. | Milisegundos |
| `ErrorRate` | Media, Suma | La tasa de solicitudes que fallaron con un código de estado `4xx Client Error`, lo que da lugar a un error. | Porcentaje |
| `FaultRate` | Media, Suma | La tasa de seguimientos que fallaron con un código de estado `5xx Server Error`, lo que da lugar a un fallo. | Porcentaje |
| `ThrottleRate` | Media, Suma | La tasa de registros limitas que devuelven un código de estado `429`. Se trata de un subconjunto de la métrica `ErrorRate`. | Porcentaje |
| `OkRate` | Media, Suma | La tasa de solicitudes rastreadas que dan lugar a un código de estado `OK`. | Porcentaje |
### CloudWatch Dimensiones de X-Ray
Utilice las dimensiones de la siguiente tabla para ajustar las métricas devueltas para sus aplicaciones de Java instrumentadas de X-Ray.
| Dimensión | Description (Descripción) |
| --- | --- |
| `ServiceType` | El tipo de servicio, por ejemplo, `AWS::EC2::Instance` o `NONE`, si no se conoce. |
| `ServiceName` | El nombre canónico del servicio. |
### Habilitar las CloudWatch métricas de X-Ray
Utilice el siguiente procedimiento para habilitar métricas de rastreo en su aplicación de Java instrumentada.
**Para configurar las métricas de seguimiento**
1. Agregue el paquete `aws-xray-recorder-sdk-metrics` como una dependencia de Apache Maven. Para obtener más información, consulte [Submódulos del SDK de X-Ray para Java](#xray-sdk-java-submodules).
1. Habilite un nuevo `MetricsSegmentListener()` como parte de la compilación de la grabadora global.
**Example src/com/myapp/web/Startup.java**
```
import com.amazonaws.xray.AWSXRay;
import com.amazonaws.xray.AWSXRayRecorderBuilder;
import com.amazonaws.xray.plugins.EC2Plugin;
import com.amazonaws.xray.plugins.ElasticBeanstalkPlugin;
import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy;
@Configuration
public class WebConfig {
...
static {
AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder
.standard()
.withPlugin(new EC2Plugin())
.withPlugin(new ElasticBeanstalkPlugin())
.withSegmentListener(new MetricsSegmentListener());
URL ruleFile = WebConfig.class.getResource("/sampling-rules.json");
builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile));
AWSXRay.setGlobalRecorder(builder.build());
}
}
```
1. Implemente el CloudWatch agente para recopilar métricas mediante Amazon Elastic Compute Cloud (Amazon EC2), Amazon Elastic Container Service (Amazon ECS) o Amazon Elastic Kubernetes Service (Amazon EKS):
+ Para configurar Amazon EC2, consulte [Instalación del CloudWatch agente](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-on-EC2-Instance.html).
+ Para configurar Amazon ECS, consulte [Supervisión de los contenedores de Amazon ECS mediante Información de contenedores](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cloudwatch-container-insights.html).
+ Para configurar Amazon EKS, consulte [Instalación del CloudWatch agente mediante el complemento Amazon CloudWatch Observability EKS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html).
1. Configure el SDK para que se comunique con el CloudWatch agente. De forma predeterminada, el SDK se comunica con el CloudWatch agente en la dirección`127.0.0.1`. Puede configurar direcciones alternativas al configurar el entorno variable o la propiedad de Java en `address:port`.
**Example Variable de entorno**
```
AWS_XRAY_METRICS_DAEMON_ADDRESS=address:port
```
**Example Propiedad de Java**
```
com.amazonaws.xray.metrics.daemonAddress=address:port
```
**Para validar la configuración**
1. Inicie sesión en Consola de administración de AWS y abra la CloudWatch consola en [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Abra la pestaña **Metrics (Métricas)** para observar el flujo de sus métricas.
1. (Opcional) En la CloudWatch consola, en la pestaña **Registros**, abra el grupo de `ServiceMetricsSDK` registros. Busque un flujo de registros que coincida con las métricas del host y confirme los mensajes del registro.
# Transmisión de contexto de segmento entre subprocesos en una aplicación multiproceso
**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 se crea un nuevo subproceso en la aplicación, el `AWSXRayRecorder` no mantiene una referencia al segmento o subsegmento [Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html) actual. Si utilizas un cliente instrumentado en el nuevo hilo, el SDK intenta escribir en un segmento que no existe, lo que provoca un. [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html)
Para evitar que se produzcan excepciones durante el desarrollo, puedes configurar la grabadora con una [ContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/strategy/ContextMissingStrategy.html)que le indique que registre un error en su lugar. Puede configurar la estrategia en código con [SetContextMissingStrategy](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#setContextMissingStrategy(com.amazonaws.xray.strategy.ContextMissingStrategy)), o configurar opciones equivalentes con, una [variable de entorno](xray-sdk-java-configuration.md#xray-sdk-java-configuration-envvars) o una [propiedad del sistema](xray-sdk-java-configuration.md#xray-sdk-java-configuration-sysprops).
Una forma de abordar el error consiste en utilizar un segmento nuevo llamando a [beginSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#beginSegment(java.lang.String)) al iniciar el subproceso y a [endSegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html#endSegment--) al cerrarlo. Esto funciona si está instrumentando código que no se ejecuta en respuesta a una solicitud HTTP, como código que se ejecuta cuando se inicia la aplicación.
Si utiliza varios subprocesos para gestionar las solicitudes entrantes, puede transferir el segmento o subsegmento actual al nuevo subproceso y facilitarlo a la grabadora global. De este modo, se garantiza que la información registrada en el nuevo subproceso esté asociada al mismo segmento que el resto de la información registrada sobre dicha solicitud. Una vez que el segmento esté disponible en el nuevo hilo, puede ejecutar cualquier ejecutable con acceso al contexto de ese segmento mediante el método `segment.run(() -> { ... })`.
Consulte [Uso de clientes instrumentados en subprocesos de trabajo](scorekeep-workerthreads.md) para ver un ejemplo.
## Uso de X-Ray con programación asíncrona
El SDK de X-Ray para Java se puede utilizar en programas Java asíncronos con. [SegmentContextExecutors](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/contexts/SegmentContextExecutors.html) SegmentContextExecutor Implementa la interfaz Executor, lo que significa que se puede transferir a todas las operaciones asíncronas de un. [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) Eso garantiza que cualquier operación asíncrona se ejecute con el segmento correcto en su contexto.
**Example Ejemplo: App.java: Pasando a SegmentContextExecutor CompletableFuture**
```
DynamoDbAsyncClient client = DynamoDbAsyncClient.create();
AWSXRay.beginSegment();
// ...
client.getItem(request).thenComposeAsync(response -> {
// If we did not provide the segment context executor, this request would not be traced correctly.
return client.getItem(request2);
}, SegmentContextExecutors.newSegmentContextExecutor());
```
# AOP con Spring y el SDK de X-Ray para Java
**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
En este tema se describe cómo utilizar el SDK de X-Ray y el marco de trabajo Spring para instrumentar una aplicación sin cambiar su lógica básica. Esto significa que ahora existe una forma no invasiva de instrumentar las aplicaciones que se ejecutan de forma remota. AWS
**Para habilitar AOP en Spring**
1. [Configure Spring](#xray-sdk-java-aop-spring-configuration)
1. [Añada un filtro de rastreo a la aplicación](#xray-sdk-java-aop-filters-spring).
1. [Comente el código o implemente una interfaz](#xray-sdk-java-aop-annotate-or-implement)
1. [Active X-Ray en la aplicación](#xray-sdk-java-aop-activate-xray)
## Configuración de Spring
Puede utilizar Maven o Gradle para configurar Spring para que utilice AOP con el fin de instrumentar la aplicación.
Si utiliza Maven para compilar la aplicación, añada la siguiente dependencia al archivo `pom.xml`.
```
com.amazonaws
aws-xray-recorder-sdk-spring
2.11.0
```
Para Gradle, añada la siguiente dependencia al archivo `build.gradle`.
```
compile 'com.amazonaws:aws-xray-recorder-sdk-spring:2.11.0'
```
## Configuración de Spring Boot
Además de la dependencia de Spring descrita en la sección anterior, si utiliza Spring Boot, añada la siguiente dependencia si aún no está en su classpath.
Maven:
```
org.springframework.boot
spring-boot-starter-aop
2.5.2
```
Gradle:
```
compile 'org.springframework.boot:spring-boot-starter-aop:2.5.2'
```
## Adición de un filtro de rastreo a la aplicación
Añada un `Filter` a su clase `WebConfig`. Pase el nombre del segmento al constructor [https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html) como cadena. Para obtener más información sobre los filtros de rastreo y la instrumentación de las solicitudes entrantes, consulte [Rastreo de las solicitudes entrantes con el SDK de X-Ray para Java](xray-sdk-java-filters.md).
**Example src/main/java/myapp/WebConfig.java: primavera**
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import javax.servlet.Filter;
import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html);
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
}
```
## Compatibilidad con Jakarta
Spring 6 usa [Jakarta](https://spring.io/blog/2022/11/16/spring-framework-6-0-goes-ga) en lugar de Javax para su Enterprise Edition. Para admitir este nuevo espacio de nombres, X-Ray ha creado un conjunto paralelo de clases que viven en su propio espacio de nombres de Yakarta.
Para las clases de filtro, sustituya `javax` por `jakarta`. Al configurar una estrategia de nomenclatura de segmentos, agregue `jakarta` antes del nombre de la clase de estrategia de nomenclatura, como en el siguiente ejemplo:
```
package myapp;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Bean;
import jakarta.servlet.Filter;
import com.amazonaws.xray.jakarta.servlet.AWSXRayServletFilter;
import com.amazonaws.xray.strategy.jakarta.SegmentNamingStrategy;
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter(SegmentNamingStrategy.dynamic("Scorekeep"));
}
}
```
## Anotación del código o implementación de una interfaz
Las clases deben anotarse con la anotación `@XRayEnabled` o deben implementar la interfaz de `XRayTraced`. Esto indica al sistema de AOP que encapsule las funciones de la clase afectada para la instrumentación de X-Ray.
## Activación de X-Ray en la aplicación
Para activar el rastreo de X-Ray en la aplicación, el código debe extender la clase abstracta `BaseAbstractXRayInterceptor` anulando los siguientes métodos.
+ `generateMetadata`: esta función permite la personalización de los metadatos adjuntados al rastreo de la función actual. De forma predeterminada, el nombre de clase de la función que se ejecuta se registra en los metadatos. Puede añadir más datos si necesita más información.
+ `xrayEnabledClasses`: esta función está vacía, y debe seguir así. Sirve para alojar un conjunto de puntos de unión (pointcut) que indica al interceptor los métodos que debe encapsular. Defina el pointcut especificando las clases que se han anotado con `@XRayEnabled` que se deben rastrear. La siguiente instrucción pointcut indica al interceptor que encapsule todos los beans del controlador anotados con la anotación `@XRayEnabled`.
```
@Pointcut(“@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)”)
```
Si su proyecto utiliza Spring Data JPA, considere la posibilidad de ampliar desde `AbstractXRayInterceptor` en lugar de `BaseAbstractXRayInterceptor`.
## Ejemplo
El siguiente código extiende la clase abstracta `BaseAbstractXRayInterceptor`.
```
@Aspect
@Component
public class XRayInspector extends BaseAbstractXRayInterceptor {
@Override
protected Map> generateMetadata(ProceedingJoinPoint proceedingJoinPoint, Subsegment subsegment) throws Exception {
return super.generateMetadata(proceedingJoinPoint, subsegment);
}
@Override
@Pointcut("@within(com.amazonaws.xray.spring.aop.XRayEnabled) && bean(*Controller)")
public void xrayEnabledClasses() {}
}
```
El siguiente código es una clase que X-Ray va a instrumentar.
```
@Service
@XRayEnabled
public class MyServiceImpl implements MyService {
private final MyEntityRepository myEntityRepository;
@Autowired
public MyServiceImpl(MyEntityRepository myEntityRepository) {
this.myEntityRepository = myEntityRepository;
}
@Transactional(readOnly = true)
public List getMyEntities(){
try(Stream entityStream = this.myEntityRepository.streamAll()){
return entityStream.sorted().collect(Collectors.toList());
}
}
}
```
Si ha configurado correctamente la aplicación, debe ver la pila de llamadas completa de la aplicación, desde el controlador hasta las llamadas a los servicios, tal y como se muestra en la siguiente captura de pantalla de la consola.
![\[Timeline showing API call duration and breakdown of server operations for metering service.\]](http://docs.aws.amazon.com/es_es/xray/latest/devguide/images/aop-spring-console.png)