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 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.