# Depuración de aplicaciones con Instrumentación dinámica
La Instrumentación dinámica permite capturar el estado del tiempo de ejecución de una aplicación activa sin reiniciarla ni volver a implementarla. El estado del tiempo de ejecución incluye valores de variables, argumentos de métodos, valores devueltos y seguimientos de pila. Defina configuraciones de instrumentación que especifiquen en qué parte del código se capturarán los datos. El agente en ejecución instrumenta la aplicación durante el tiempo de ejecución.
## Conceptos
Punto de interrupción
Instrumentación temporal que caduca automáticamente. El período de caducidad predeterminado es de 24 horas y se puede configurar entre 5 minutos y 24 horas. Utilice puntos de interrupción para la depuración y la investigación.
Sonda
Instrumentación permanente que se conserva hasta que se elimina explícitamente. Utilice sondas para mantener una observabilidad continua.
Instantánea
Captura del estado del programa en un momento específico, que incluye variables locales, argumentos, el valor devuelto, excepciones y el seguimiento de pila. Instrumentación dinámica emite instantáneas como entradas de registro en Registros de CloudWatch.
Ubicación
Ubicación del código donde se aplica la instrumentación. Los campos obligatorios varían según el lenguaje.
## Lenguajes admitidos
+ Java
+ Python
+ JavaScript o TypeScript
## Requisitos previos
Para utilizar la Instrumentación dinámica, actualice los componentes de instrumentación a la versión más reciente según el tipo de implementación:
+ **Clientes de Amazon EKS:** actualice el complemento de observabilidad de Amazon CloudWatch para EKS a la versión más reciente. El complemento incluye el SDK de ADOT y el agente de CloudWatch. Para obtener más información, consulte [Instalación del complemento de observabilidad de CloudWatch para EKS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/install-CloudWatch-Observability-EKS-addon.html).
+ **Todos los demás clientes**: actualice los dos componentes siguientes:
+ El SDK de instrumentación de la Distribución de AWS para OpenTelemetry (ADOT) correspondiente al lenguaje que utilice: Java, Python o Node.js.
+ El agente de CloudWatch a la versión más reciente.
También se deben cumplir las siguientes condiciones:
+ CloudWatch Application Signals debe estar habilitado para la aplicación.
+ Establezca la variable de entorno `OTEL_AWS_DYNAMIC_INSTRUMENTATION_ENABLED=true` en la aplicación.
+ Establezca la variable de entorno `OTEL_SERVICE_NAME` en el nombre del servicio.
+ Establezca la variable de entorno `OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name={{my_deployment_env_name}}`. Para los usuarios actuales de Application Signals, el valor debe coincidir con el nombre del entorno del servicio tal como aparece en la consola de Application Signals.
+ El agente de CloudWatch se debe ejecutar con la configuración de Application Signals.
+ La Instrumentación dinámica no es compatible con los entornos de Lambda.
## Incorporación de Instrumentación dinámica a la aplicación
Después de instrumentar la aplicación (consulte [Requisitos previos](#Application-Signals-DI-Prerequisites)), cree una *configuración de instrumentación* que especifique en qué parte del código se incorporará la telemetría dinámica. Cada configuración define dos aspectos:
1. **Ubicación del código que se supervisará**: ubicación del código donde se aplica el punto de interrupción o la sonda.
1. **Datos que se capturarán**: estado del tiempo de ejecución que se captura cuando se ejecuta el punto de interrupción o la sonda.
**nota**
De forma predeterminada, la Instrumentación dinámica solo captura una cantidad limitada de datos. Para aprovechar al máximo esta característica, considere ampliar la configuración de captura mediante las opciones que se describen en [Límites de captura](#Application-Signals-DI-Limits).
Puede crear configuraciones mediante AWS CLI o el SDK, o mediante el servidor del Protocolo de contexto para modelos (MCP) con un asistente de codificación de IA en el entorno de desarrollo integrado (IDE).
### Creación de configuraciones mediante la CLI o el SDK
Utilice AWS CLI o el SDK de AWS para crear configuraciones de instrumentación mediante programación.
#### Especificación de la ubicación del código
La ubicación define en qué parte del código se aplica la instrumentación. Los campos obligatorios varían según el lenguaje:
| Idioma | Campos obligatorios | Campos opcionales |
| --- | --- | --- |
| Java | CodeUnit (paquete), ClassName, MethodName, FilePath | LineNumber |
| Python | CodeUnit (módulo), MethodName, FilePath | LineNumber, ClassName |
| JavaScript o TypeScript | FilePath, LineNumber | Ninguna. Solo se admiten puntos de interrupción a nivel de línea. No se admiten sondas ni puntos de interrupción a nivel de función. TypeScript es compatible cuando se proporcionan mapas de origen. |
#### Configuración de los datos que se capturarán
La configuración de captura controla qué estado del tiempo de ejecución se recopila cuando se activa la instrumentación. Opciones disponibles:
+ `CaptureArguments`: lista de nombres de argumentos de métodos que se capturarán.
+ `CaptureReturn`: captura del valor devuelto (booleano).
+ `CaptureStackTrace`: captura del seguimiento de pila (booleano).
+ `CaptureLocals`: lista de nombres de variables locales que se capturarán.
+ `CaptureLimits`: control de la profundidad y el tamaño de la captura (consulte [Límites de captura](#Application-Signals-DI-Limits)).
#### Parámetros de configuración
Parámetros principales para crear una configuración:
+ `instrumentation-type` — `BREAKPOINT` o bien `PROBE`
+ `service`: nombre del servicio tal como aparece en Application Signals
+ `environment`: nombre del entorno
+ `signal-type` — `SNAPSHOT`
+ `location`: campos de ubicación del código (consulte la información anterior)
+ `capture-configuration`: opciones de captura (consulte la información anterior)
#### Ejemplo
El siguiente ejemplo crea un punto de interrupción en un método de Java:
```
aws application-signals create-instrumentation-configuration \
--instrumentation-type BREAKPOINT \
--service "my-service" \
--environment "production" \
--signal-type SNAPSHOT \
--location '{
"CodeLocation": {
"Language": "Java",
"CodeUnit": "com.example.service",
"ClassName": "OrderController",
"MethodName": "processOrder",
"FilePath": "OrderController.java"
}
}' \
--capture-configuration '{
"CodeCapture": {
"CaptureArguments": ["orderId", "user"],
"CaptureReturn": true,
"CaptureStackTrace": true,
"CaptureLimits": {
"MaxHits": 100,
"MaxStringLength": 255,
"MaxCollectionWidth": 20,
"MaxObjectDepth": 3,
"MaxFieldsPerObject": 20,
"MaxStackFrames": 20
}
}
}'
```
### Creación de configuraciones mediante el servidor MCP
El enfoque recomendado para utilizar la Instrumentación dinámica consiste en usar el servidor MCP (protocolo de contexto para modelos) de CloudWatch Application Signals. El servidor MCP permite que los asistentes y agentes de codificación con IA del entorno de desarrollo integrado (IDE) creen, administren y consulten configuraciones de Instrumentación dinámica directamente desde el entorno de desarrollo.
Mediante el servidor MCP, el asistente de IA puede:
+ Crear puntos de interrupción y sondas en ubicaciones específicas del código sin salir del editor.
+ Consultar las instantáneas capturadas para examinar los valores de las variables durante el tiempo de ejecución y las rutas de llamadas.
+ Establecer automáticamente correlaciones entre los datos de las instantáneas y el código en el que se trabaja para sugerir correcciones.
+ Administrar el ciclo de vida de las configuraciones de instrumentación, como consultar su estado y eliminar los puntos de interrupción caducados.
Para obtener instrucciones de configuración y uso, consulte el [servidor MCP de Application Signals](https://awslabs.github.io/mcp/servers/cloudwatch-applicationsignals-mcp-server) en el sitio web de GitHub.
## Almacenamiento de datos
Cuando se activa un punto de interrupción o una sonda, la Instrumentación dinámica crea un grupo de registro en Registros de CloudWatch con el prefijo `/aws/application-signals/{{service-name}}` (donde {{service-name}} es el valor de la variable de entorno `OTEL_SERVICE_NAME`) y escribe las instantáneas capturadas como entradas de registro en ese grupo de registro.
Si el grupo de registro aún no existe, la Instrumentación dinámica lo crea automáticamente la primera vez que se emite una instantánea. Se cobrará la ingesta y el almacenamiento de registros según las tarifas estándar de Registros de CloudWatch.
## Visualización y administración de las configuraciones
En la consola de CloudWatch, vaya a la página de detalles del servicio y seleccione la pestaña **Instrumentación**.
+ Alterne entre **Puntos de interrupción** y **Sondas** para ver las configuraciones por tipo.
+ Consulte los detalles de la configuración, como la descripción, la configuración de captura, la ubicación, el ARN y la hora de caducidad.
+ Consulte el historial de estados para realizar un seguimiento de las transiciones de Listo a Activo y, posteriormente, a Error o Desactivado.
+ Elimine las configuraciones que ya no sean necesarias.
## Descripción de los estados
Cada configuración de instrumentación tiene un estado que indica su situación actual.
| Estado | Descripción |
| --- | --- |
| READY | El agente recibió la configuración. |
| ACTIVE | El agente aplicó la instrumentación a la aplicación en ejecución. |
| ERROR | No se pudo aplicar la instrumentación. Consulte la causa del error para obtener más información. |
| DISABLED | La instrumentación caducó o se eliminó. |
Cuando una instrumentación pasa al estado ERROR, puede informarse de alguna de las siguientes causas:
| Causa del error | Descripción |
| --- | --- |
| FILE\_NOT\_FOUND | La ruta del archivo especificado no existe en la aplicación. |
| METHOD\_NOT\_FOUND | El método especificado no existe en la clase o el módulo de destino. |
| LINE\_NOT\_EXECUTABLE | El número de línea especificado no corresponde a una instrucción ejecutable. |
| OVERLOADED\_METHODS | Varios métodos coinciden con el nombre especificado. Proporcione detalles adicionales sobre la ubicación para identificar el método correcto. |
| LANGUAGE\_MISMATCH | Los campos de ubicación no corresponden al lenguaje de la aplicación en ejecución. |
| RUNTIME\_ERROR | Se produjo un error inesperado al aplicar la instrumentación. |
## Límites de captura
Los límites de captura controlan el tamaño y la profundidad de los datos capturados. Configure estos valores en el campo `capture-limits` de la configuración de captura.
| Límite | Predeterminado | Range | Descripción |
| --- | --- | --- | --- |
| maxStringLength | 255 | 1 a 255 | Número máximo de caracteres que se capturan por cada valor de cadena. |
| maxCollectionWidth | 20 | 1–20 | Número máximo de elementos que se capturan por colección o matriz. |
| maxObjectDepth | 3 | 1 a 5 | Profundidad máxima del recorrido de objetos anidados. |
| maxFieldsPerObject | 20 | 1–20 | Número máximo de campos que se capturan por objeto. |
| maxStackFrames | 20 | 1–20 | Número máximo de marcos de pila que se capturan. |
| maxHits | 100 | entre 1 y 1000 | Número máximo de capturas antes de la desactivación automática. Solo se aplica a los puntos de interrupción. |
Cada punto de instrumentación tiene un límite de 5 capturas por segundo.