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

Lenguajes admitidos

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:

También se deben cumplir las siguientes condiciones:

Incorporación de Instrumentación dinámica a la aplicación

Después de instrumentar la aplicación (consulte Requisitos previos), 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:

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:

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:

Parámetros de configuración

Parámetros principales para crear una configuración:

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:

Para obtener instrucciones de configuración y uso, consulte el servidor MCP de Application Signals 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.

Descripción de los estados

Cada configuración de instrumentación tiene un estado que indica su situación actual.

Cuando una instrumentación pasa al estado ERROR, puede informarse de alguna de las siguientes causas:

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.

Cada punto de instrumentación tiene un límite de 5 capturas por segundo.