Todos los productos
Search
Centro de documentos

Cloud Monitor:Diagnóstico de aplicaciones Python con Live-Debug Agent Skill

Última actualización: Sep 08, 2026

Live-Debug Agent Skill le permite ejecutar diagnósticos en tiempo de ejecución sobre aplicaciones Python conectadas a Application Real-Time Monitoring Service (ARMS). No es necesario modificar el código de negocio, publicar una nueva versión ni reiniciar el proceso. Usted describe su intención de diagnóstico en lenguaje natural y el AI Agent orquesta automáticamente la creación del agente, la consulta de resultados mediante Simple Log Service (SLS) y la limpieza del agente a través de la API ServiceTask de Cloud Monitor (CMS).

Cuando se invoca al método objetivo, usted puede recopilar registros dinámicos, instantáneas de métodos, métricas temporales e información de trazas.

Importante

Los AI Agents funcionan con modelos de lenguaje grandes y pueden presentar riesgos, como sesgos en la identificación del módulo o método objetivo, o expresiones incorrectas. Antes de crear un agente, compruebe detenidamente la configuración y el recurso objetivo que muestra el Agent. Compruebe el impacto del agente en el rendimiento y la estabilidad dentro de un entorno de prueba antes de usarlo en producción. Una vez finalizado el diagnóstico, elimine el agente de inmediato para evitar residuos.

Escenarios

Requisito de diagnóstico

Función recomendada

Instrucción típica

Confirmar si se invoca a una función y si los parámetros de entrada cumplen las expectativas

Registro dinámico (LOG)

"Agrega un registro dinámico en la salida de la función X"

Consultar parámetros, valores de retorno, variables locales y pila de llamadas

Instantánea de método (SNAPSHOT)

"Toma una instantánea de la función X, captura..."

Capturar automáticamente el contexto cuando se lanza una excepción

Instantánea de método (excepción)

"Captura una instantánea cuando la función X lance una excepción"

Observar temporalmente el volumen de negocio o la distribución de latencia

Métrica dinámica (METRIC)

"Agrega una métrica ... a la función X"

Agregar temporalmente un span o etiquetar un span existente con atributos de negocio

SPAN/SPAN_TAG

"Agrega un span / Etiqueta el span actual con..."

Funciones de diagnóstico compatibles

Función

Tipo de agente

taskType

Descripción

Registro dinámico

LOG

live_debug_log_probe

Genera registros de diagnóstico basados en una plantilla. No captura grafos de objetos ni pilas de llamadas.

Instantánea de método

SNAPSHOT

live_debug_snapshot_probe

Captura ARGS, RETURN, LOCALS, STACK y otros datos.

Métrica dinámica

METRIC

live_debug_metric_probe

Admite los tipos de métrica COUNTER, GAUGE, HISTOGRAM y SUMMARY.

Span dinámico

SPAN

live_debug_span_probe

Crea un span de OTel a nivel de función.

Etiquetado de spans

SPAN_TAG

live_debug_span_tag_probe

Agrega atributos al span activo actual.

Flujo de trabajo

A continuación se describe cómo el Skill orquesta una sesión de diagnóstico:

  1. Usted describe el requisito de diagnóstico (qué función observar, qué capturar y, de forma opcional, las condiciones de filtro y la duración).

  2. El Agent comprueba el entorno de la interfaz de línea de comandos (CLI) y lee .arms-info (solicita esta información si falta el archivo).

  3. El Agent genera una configuración de agente, crea la tarea y devuelve un taskId.

  4. Usted activa el tráfico del servicio correspondiente.

  5. El Agent consulta el estado de instalación y los resultados de recopilación, y los interpreta.

  6. Una vez que usted confirma que el diagnóstico terminó, el Agent elimina el agente (o limpia todos los agentes).

Requisitos previos

Condición

Descripción

Cuenta de Alibaba Cloud

Debe contar con permisos de Live-Debug (CMS ServiceTask) y de consulta de Simple Log Service en el espacio de trabajo y la aplicación objetivo.

Aplicación objetivo

La aplicación Python debe estar conectada a ARMS y tener habilitado Live-Debug.

CLI de Alibaba Cloud

Debe estar instalada y autenticada mediante aliyun configure. Además, debe poder invocar cms2 (plugin aliyuncms2 de la CLI de CMS) y sls. Para consultar las instrucciones de instalación, consulte el Paso 1 más adelante.

AI Agent

Debe tener instalado QoderWork, Cursor, Claude Code u otra herramienta compatible con Agent Skills. Para consultar las instrucciones de instalación del Skill, consulte el Paso 2 más adelante.

Información de conexión de la aplicación

Debe preparar workspace, serviceId, regionId y slsProject (consulte el Paso 3).

Paso 1: Instalar y configurar la CLI de Alibaba Cloud

Live-Debug Skill invoca a CMS (aliyun cms2 apm service-task para crear, listar y eliminar tareas) y a Simple Log Service (para consultar los resultados de recopilación) mediante la CLI aliyun. Complete primero la instalación de la CLI y la configuración de credenciales.

Instalar la CLI

Si la CLI no está instalada, consulte Install Alibaba Cloud CLI y seleccione el método de instalación correspondiente a su sistema operativo (Linux, macOS o Windows).

Después de la instalación, compruebe que la CLI esté disponible:

aliyun version

Configurar las credenciales de acceso

aliyun configure

Introduzca el AccessKey ID, el AccessKey secret y la región predeterminada según las indicaciones. Use un usuario de RAM y otórguele permisos de CMS ServiceTask, así como permisos de lectura, escritura y consulta en el proyecto de Simple Log Service objetivo. Para obtener más información, consulte Configure and manage identity credentials.

Nota

Cuando Live-Debug consulta resultados, especifica explícitamente regionId (obtenido de .arms-info). No dependa únicamente de la región predeterminada configurada en aliyun configure. Si la región predeterminada no coincide con el proyecto de Simple Log Service, podría producirse un error ProjectNotExist.

Instalar la CLI de CMS (aliyuncms2) y comprobar su disponibilidad

Las funciones de CMS ServiceTask las proporciona el binario del plugin aliyuncms2. Obtenga aliyuncms2 y colóquelo en el directorio ~/.aliyun/ (o en PATH). Después podrá invocarlo mediante aliyun cms2, y las credenciales se reutilizarán desde la configuración de aliyun configure.

# Verify CMS ServiceTask capabilities
aliyun cms2 apm service-task --help

# Verify SLS query availability
aliyun sls --help

Si cms2 no está disponible, compruebe que el binario aliyuncms2 se encuentre en ~/.aliyun/ (o en PATH) y tenga permisos de ejecución:

ls -l ~/.aliyun/aliyuncms2
chmod +x ~/.aliyun/aliyuncms2
aliyun cms2 apm service-task --help

Si el problema persiste, actualice la CLI de Alibaba Cloud e inténtelo de nuevo:

aliyun upgrade -y

Paso 2: Instalar Live-Debug agent skill

  1. Obtenga Live-Debug Agent Skill e instálelo en su AI Agent con un solo clic mediante alibabacloud-livedebug.

  2. Siga las instrucciones de su herramienta de IA para instalar el Skill en QoderWork, Cursor, Claude Code u otro entorno.

  3. Después de la instalación, reinicie el asistente de IA o confirme mediante una conversación que el Skill se cargó (por ejemplo, pregunte "¿Ya cargaste el Live-Debug Skill?").

En las siguientes secciones, ${LIVE_DEBUG_SKILL_ROOT} representa el directorio raíz de instalación del Skill. Los scripts complementarios se ubican en ${LIVE_DEBUG_SKILL_ROOT}/scripts/.

Paso 3: Preparar la información de conexión de la aplicación

Cree el archivo .arms-info (formato key=value) en el directorio raíz del proyecto que va a diagnosticar para que el Agent lo lea automáticamente. También puede proporcionar esta misma información directamente en la conversación.

workspace=default-cms-xxxxxxxxxxxxxxxxxx-cn-hangzhou
serviceId=ggxw4lnjuz@f2fd3a6265a254a052afb
regionId=cn-hangzhou
targetIp=*
slsProject=proj-xtrace-xxxxxxxxxxxxxxxxxxxxxx-cn-hangzhou

Parámetro

Obligatorio

Descripción

workspace

Sí

Identificador del espacio de trabajo de ARMS.

serviceId

Sí

Identificador de la aplicación o del servicio.

regionId

Sí

Región de acceso, como cn-hangzhou.

slsProject

Sí

Proyecto de Simple Log Service que almacena los resultados de Live-Debug.

targetIp

No

Dirección IP de la instancia objetivo. Valor predeterminado: * (todas las instancias).

Paso 4: Iniciar el diagnóstico con lenguaje natural

Se recomienda abrir el código de su proyecto con una herramienta de AI Coding como Qoder, cambiar a la rama correspondiente a su aplicación en producción y luego iniciar el diagnóstico con lenguaje natural dentro de dicha herramienta. Al describir el requisito de diagnóstico, incluya la siguiente información (el Agent la solicitará si falta algún dato):

Información

Obligatoria

Ejemplo

Ubicación objetivo

Sí

OrderService.create_order en app.service.order, o la línea N de un archivo específico.

Momento de observación

Recomendada

Entrada, salida, al producirse una excepción o en una línea específica (el valor predeterminado suele ser la salida).

Contenido por observar

Sí

Parámetros de entrada, valor de retorno, latencia, variables locales o pila de llamadas.

Condición de filtro

No

Solo cuando amount > 10000.

Duración o cantidad

No

30 minutos, o detener tras 50 capturas.

Una vez creada la tarea, el Agent devuelve un taskId. Compare las configuraciones de referencia en Reference configurations para comprobar que los campos de módulo objetivo, método, location, plantilla o capture sean correctos. Después, active el tráfico del servicio.

Paso 5: Activar el tráfico, comprobar los resultados y limpiar

  1. Comprobar la configuración: Confirme que el taskConfig enviado por el Agent coincida con las configuraciones de referencia en cuanto a ubicación objetivo y contenido de recopilación.

  2. Activar el tráfico del servicio: Envíe una o más solicitudes a una interfaz que alcance la ruta de código objetivo.

  3. Consultar los resultados: Indique al Agent:

    Query the collection results for the taskId from just now, and help me interpret whether the agent is installed and what was captured.
    • Task Status: Indica si el agente se instaló correctamente, las métricas de embudo y otra información de estado.

    • Capture Results: El contenido recopilado, como registros e instantáneas.

  4. Limpiar (ejecute siempre este paso):

    Delete the agent from just now.
    Clear all Live-Debug agents for the current service.
    Show me what Live-Debug agents are still attached to the current service.

Configuraciones de referencia

Use las siguientes configuraciones de referencia para comprobar el taskConfig que genera el Agent. Cada subsección corresponde a un tipo de agente de la tabla Supported diagnostics capabilities.

Registro dinámico (LOG)

Instrucción de ejemplo:

Use the /alibabacloud-livedebug Skill to add a dynamic log at the exit of OrderService.create_order in app.service.order, print order_id, amount, return value, and latency. Keep it for 30 minutes.

Configuración de referencia:taskType = live_debug_log_probe

{
  "probeType": "LOG",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "LOG",
    "template": "create_order id={order_id} amount={amount} ret={@return} cost={@duration}ms"
  },
  "ttl": "30m",
  "captureCount": 100
}

A nivel de línea con condición:

Add a log at line 42 of app/service/order.py. Only output the order ID and amount when amount >= 1000.

Configuración de referencia:taskType = live_debug_log_probe

{
  "probeType": "LOG",
  "language": "python",
  "target": {
    "sourceFile": "app/service/order.py",
    "location": "line:42",
    "instanceIds": ["*"]
  },
  "trigger": {
    "condition": "amount >= 1000"
  },
  "action": {
    "type": "LOG",
    "template": "big order id={order_id} amount={amount}"
  },
  "ttl": "30m"
}

Instantánea de método (SNAPSHOT)

Instrucción de ejemplo:

Use the /alibabacloud-livedebug Skill to take a snapshot at the exit of OrderService.create_order. Capture input parameters, local variables, return value, and call stack. Capture up to 20 times.

Configuración de referencia:taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS", "LOCALS", "RETURN", "STACK"],
    "captureConfig": {
      "maxDepth": 3,
      "maxCollectionSize": 100,
      "maxStringLength": 1024
    }
  },
  "ttl": "30m",
  "captureCount": 20
}

Filtrado condicional con campos personalizados:

Take a snapshot at the exit of create_order. Trigger only when the return value is empty or the amount is greater than 10000. Focus on order_id, amount * count, self.user_id, and the return value.

Configuración de referencia:taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "trigger": {
    "condition": "@return is None or amount > 10000"
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS"],
    "captureExpressions": [
      "order_id",
      "amount * count",
      "self.user_id",
      "@return"
    ]
  },
  "ttl": "30m",
  "captureCount": 50
}

Captura de excepciones:

Capture a snapshot when PaymentService.process_payment throws an exception. Include input parameters, exception information, and call stack. Keep it for 2 hours.

Configuración de referencia:taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.payment",
    "methodName": "PaymentService.process_payment",
    "location": "exception",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS", "EXCEPTION", "STACK", "LOCALS"]
  },
  "ttl": "2h",
  "captureCount": 100
}

Métrica dinámica (METRIC)

Instrucción de ejemplo:

Use the /alibabacloud-livedebug Skill to add an amount histogram metric to create_order. Include a tag indicating whether the user is a VIP. Keep it for 1 hour.

Configuración de referencia:taskType = live_debug_metric_probe

{
  "probeType": "METRIC",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "METRIC",
    "metricName": "livedebug.order.amount",
    "metricType": "HISTOGRAM",
    "valueExpression": "amount",
    "tags": {
      "is_vip": "str(user_id == 'vip')"
    }
  },
  "ttl": "1h"
}

Span dinámico (SPAN)

Instrucción de ejemplo:

Use the /alibabacloud-livedebug Skill to temporarily add a span on OrderService.create_order named dyn.create_order. Include the order ID and amount as span attributes.

Configuración de referencia:taskType = live_debug_span_probe

{
  "probeType": "SPAN",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "enter",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SPAN",
    "spanName": "dyn.create_order",
    "spanTags": {
      "order.id": "str(order_id)",
      "order.amount": "str(amount)"
    }
  },
  "ttl": "1h"
}

Etiquetado de spans (SPAN_TAG)

Instrucción de ejemplo:

At the exit of create_order, use the /alibabacloud-livedebug Skill to tag the current span with order.id and order.result (use the return value). Do not create a new span.

Configuración de referencia:taskType = live_debug_span_tag_probe

{
  "probeType": "SPAN_TAG",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SPAN_TAG",
    "tags": [
      {"key": "order.id", "value": "str(order_id)"},
      {"key": "order.result", "value": "str(@return)"}
    ]
  },
  "ttl": "1h"
}

Paso 5: Activar el tráfico, validar los resultados y limpiar

  1. Comprobar la configuración: Confirme que el taskConfig enviado por el agente coincida con la configuración de referencia en cuanto a ubicación objetivo y contenido por capturar.

  2. Activar el tráfico: Envíe una o más solicitudes a la API que ejecuta la ruta de código objetivo.

  3. Consultar los resultados: Consulte al agente para obtener los siguientes resultados:

    Show me the capture results for the last task ID, and tell me if the probe was installed and what was captured.
    • Task Status: Este estado indica si la sonda se instaló correctamente y proporciona métricas de embudo junto con otros detalles.

    • Capture Results: Incluye el contenido capturado, como registros e instantáneas.

  4. Limpiar (obligatorio):

    Delete the previous probe.
    Delete all Live-Debug probes in the current service.
    Show me which Live-Debug probes are still active in the current service.

Referencia rápida de escenarios

Necesidad de diagnóstico

Es decir

taskType correspondiente

Confirmar rápidamente la llamada a una función

"Agrega un registro dinámico en la salida de la función X e imprime..."

live_debug_log_probe

Inspeccionar parámetros, valores de retorno o la pila

"Toma una instantánea de la función X y recopila..."

live_debug_snapshot_probe

Capturar el contexto solo ante excepciones

"Cuando la función X lance una excepción, captura una instantánea"

live_debug_snapshot_probe

Consultar variables cerca de una línea específica

"En el archivo X, en la línea N, agrega un registro o toma una instantánea"

live_debug_log_probe / live_debug_snapshot_probe

Métrica temporal

"Asocia una métrica ... a la función X"

live_debug_metric_probe

Relleno y etiquetado ad hoc

"Agrega un Span a la función X o agrega una etiqueta ... al Span actual"

live_debug_span_probe / live_debug_span_tag_probe

Consultar resultados

"Consulta e interpreta los resultados de taskId=..."

— (Consulta en SLS)

Limpiar

"Elimina este agente" o "Elimina todos los agentes"

— (Eliminación)

Preguntas frecuentes

El agente informa que el comando cms2 o aliyun no está disponible

Causa: La CLI de Alibaba Cloud no está instalada, la versión es demasiado antigua o el binario del plugin aliyuncms2 no está listo.

Solución:

aliyun version
aliyun upgrade -y
ls -l ~/.aliyun/aliyuncms2   # Confirm the CMS CLI plugin binary exists and is executable
aliyun cms2 apm service-task --help
aliyun sls --help

Asegúrese de haber ejecutado aliyun configure para configurar el par de AccessKey.

La tarea se creó correctamente, pero no aparecen resultados de captura

Resuelva el problema en el siguiente orden:

  1. Pida al Agent que compruebe primero el Task Status y confirme si el agente se instaló correctamente.

  2. Compruebe que typeName y methodName coincidan con el nombre del módulo en tiempo de ejecución y con __qualname__. Verifique si el módulo principal debería ser __main__.

  3. Confirme que activó una solicitud que alcanza la función objetivo. Revise si la condición de filtro es demasiado restrictiva.

  4. Confirme que regionId en .arms-info coincida con la región de slsProject.

  5. Amplíe la ventana de tiempo de la consulta e inténtelo de nuevo.

También puede indicar al Agent: "No se capturaron datos. Ayúdame a comprobar si el estado y la ubicación objetivo son correctos".

SLS reporta ProjectNotExist

Causa: La región utilizada para la consulta no coincide con la región del proyecto de Simple Log Service.

Solución: Introduzca el regionId correcto en .arms-info y asegúrese de que el Agent haya exportado LIVE_DEBUG_REGION_ID. No dependa exclusivamente de la región predeterminada de la CLI.

Cómo confirmar que los agentes se limpiaron

Show me what Live-Debug agents are still attached to the current service. If there are any, delete all of them.

¿Las aplicaciones Python admiten diagnósticos de hilos, memoria o descompilación?

No. Estas son funciones de Command que solo se admiten en aplicaciones Java/JVM. Para aplicaciones Python, utilice diagnósticos de registros, instantáneas, métricas o spans.

Referencias