Todos os produtos
Search
Central de documentação

Cloud Monitor:Diagnosticar aplicações Python com o Live-Debug Agent Skill

Última atualização: Aug 03, 2026

O Live-Debug Agent Skill permite diagnosticar aplicações Python conectadas ao Application Real-Time Monitoring Service (ARMS) ou ao Managed Service for OpenTelemetry em tempo de execução, sem modificar o código de negócio, lançar uma nova versão ou reiniciar o processo. Descreva sua intenção de diagnóstico em linguagem natural e o AI Agent orquestrará automaticamente a criação da sonda, a consulta de resultados via Simple Log Service (SLS) e a limpeza da sonda por meio da API ServiceTask do Cloud Monitor (CMS).

Ao chamar o método alvo, colete logs dinâmicos, snapshots de métodos, métricas temporárias e informações de rastreamento.

Importante

Os AI Agents utilizam modelos de linguagem grandes e podem apresentar riscos, como viés na identificação de módulos ou métodos alvo e expressões incorretas. Antes de criar uma sonda, verifique cuidadosamente a configuração e o recurso alvo exibidos pelo Agent. Valide o impacto da sonda no desempenho e na estabilidade em um ambiente de teste antes de usá-la em produção. Após concluir o diagnóstico, exclua a sonda imediatamente para evitar resíduos.

Cenários

Necessidade de diagnóstico

Recurso recomendado

Exemplo de comando

Confirmar se uma função foi chamada e se os parâmetros de entrada atendem às expectativas

Log dinâmico (LOG)

"Adicionar um log dinâmico na saída da função X"

Visualizar parâmetros, valores de retorno, variáveis locais e pilha de chamadas

Snapshot de método (SNAPSHOT)

"Tirar um snapshot da função X, capturar ..."

Capturar automaticamente o cenário quando uma exceção for lançada

Snapshot de método (exceção)

"Capturar um snapshot quando a função X lançar uma exceção"

Observar temporariamente o volume de negócios ou a distribuição de latência

Métrica dinâmica (METRIC)

"Adicionar uma métrica ... à função X"

Adicionar temporariamente um span ou marcar um span existente com atributos de negócio

SPAN / SPAN_TAG

"Adicionar um span / Marcar o span atual com ..."

Recursos de diagnóstico suportados

Recurso

Tipo de sonda

taskType

Descrição

Log dinâmico

LOG

live_debug_log_probe

Gera logs de diagnóstico com base em um modelo. Não captura grafos de objetos ou pilhas de chamadas.

Snapshot de método

SNAPSHOT

live_debug_snapshot_probe

Captura ARGS, RETURN, LOCALS, STACK e outros dados.

Métrica dinâmica

METRIC

live_debug_metric_probe

Suporta os tipos de métrica COUNTER, GAUGE, HISTOGRAM e SUMMARY.

Span dinâmico

SPAN

live_debug_span_probe

Cria um span OTel no nível da função.

Marcação de span

SPAN_TAG

live_debug_span_tag_probe

Acrescenta atributos ao span ativo atual.

Fluxo de trabalho

Veja como o Skill orquestra uma sessão de diagnóstico:

  1. Descreva a necessidade de diagnóstico (qual função observar, o que capturar e, opcionalmente, condições de filtro e duração).

  2. O Agent verifica o ambiente da interface de linha de comando (CLI) e lê o arquivo .arms-info (solicita-o caso esteja ausente).

  3. O Agent gera uma configuração de sonda, cria a tarefa e retorna um taskId.

  4. Acione o tráfego do service relevante.

  5. O Agent consulta o status de instalação e os resultados da coleta e os interpreta.

  6. Após você confirmar a conclusão do diagnóstico, o Agent exclui a sonda (ou limpa todas as sondas).

Pré-requisitos

Condição

Descrição

Conta Alibaba Cloud

Possui permissões de consulta no Live-Debug (CMS ServiceTask) e no Simple Log Service para o workspace e a aplicação alvo.

Aplicação alvo

Uma aplicação Python conectada ao ARMS (ou a um LoongSuite / OpenTelemetry Python Agent compatível) com o Live-Debug ativado.

Alibaba Cloud CLI

Instalado e autenticado via aliyun configure. Deve ser capaz de chamar cms2 (plugin CMS CLI aliyuncms2) e sls. Para instruções de instalação, consulte a Etapa 1 abaixo.

AI Agent

QoderWork, Cursor, Claude Code ou outra ferramenta que suporte Agent Skills instalada. Para instruções de instalação do Skill, consulte a Etapa 2 abaixo.

Informações de conexão da aplicação

workspace, serviceId, regionId e slsProject preparados (consulte a Etapa 3).

Etapa 1: Instalar e configurar o Alibaba Cloud CLI

O Live-Debug Skill chama o CMS (aliyun cms2 apm service-task para criar, listar e excluir tarefas) e o Simple Log Service (para consultar resultados de coleta) por meio da CLI aliyun. Conclua primeiro a instalação da CLI e a configuração das credenciais.

Instalar a CLI

Caso a CLI não esteja instalada, consulte Install Alibaba Cloud CLI e selecione o método de instalação adequado ao seu sistema operacional (Linux, macOS ou Windows).

Após a instalação, verifique se a CLI está disponível:

aliyun version

Configurar credenciais de acesso

aliyun configure

Insira o AccessKey ID, o AccessKey secret e a região padrão conforme solicitado. Utilize um usuário RAM e conceda permissões de leitura, gravação e consulta no projeto Simple Log Service alvo, além de acesso ao CMS ServiceTask. Para mais informações, consulte Configure and manage identity credentials.

Nota

Ao consultar resultados, o Live-Debug especifica explicitamente o regionId (obtido do arquivo .arms-info). Não dependa exclusivamente da região padrão definida em aliyun configure. Se a região padrão não corresponder ao projeto do Simple Log Service, poderá ocorrer um erro ProjectNotExist.

Instalar o CMS CLI (aliyuncms2) e verificar a disponibilidade

As funcionalidades do CMS ServiceTask são fornecidas pelo binário do plugin aliyuncms2. Obtenha o aliyuncms2 e coloque-o no diretório ~/.aliyun/ (ou no PATH). Assim, você poderá chamá-lo via aliyun cms2, reutilizando as credenciais da configuração aliyun configure.

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

# Verify SLS query availability
aliyun sls --help

Se o cms2 não estiver disponível, confirme se o binário aliyuncms2 está em ~/.aliyun/ (ou no PATH) e possui permissões de execução:

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

Caso o problema persista, atualize o Alibaba Cloud CLI e tente novamente:

aliyun upgrade -y

Etapa 2: Instalar o Live-Debug agent skill

  1. Obtenha o pacote de instalação do Live-Debug Agent Skill ou a entrada no marketplace (inclui as especificações de operação SKILL.md e os scripts auxiliares em scripts/).

  2. Siga as instruções da sua ferramenta de IA para instalar o Skill no QoderWork, Cursor, Claude Code ou outro ambiente.

  3. Após a instalação, reinicie o assistente de IA ou confirme via conversa que o Skill foi carregado (por exemplo, pergunte "Você carregou o Live-Debug Skill?").

Nas seções seguintes, ${LIVE_DEBUG_SKILL_ROOT} representa o diretório raiz de instalação do Skill. Os scripts auxiliares estão localizados em ${LIVE_DEBUG_SKILL_ROOT}/scripts/.

Exemplos de gatilhos em linguagem natural:

Exemplo de palavra-chave gatilho

Recurso correspondente

"Adicionar um log dinâmico" / "Imprimir parâmetros de entrada na saída"

LOG

"Tirar um snapshot" / "Visualizar valor de retorno e pilha de chamadas"

SNAPSHOT

"Capturar quando uma exceção for lançada"

SNAPSHOT (exceção)

"Adicionar uma métrica de histograma"

METRIC

"Adicionar temporariamente um span" / "Marcar o span"

SPAN / SPAN_TAG

"Consultar resultados da coleta"

Consultar Simple Log Service

"Excluir a sonda" / "Limpar todas as sondas"

Excluir tarefa

Etapa 3: Preparar informações de conexão da aplicação

Crie o arquivo .arms-info (formato key=value) no diretório raiz do projeto a ser diagnosticado para que o Agent possa lê-lo automaticamente. Também é possível fornecer essas mesmas informações diretamente na conversa.

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

Parâmetro

Obrigatório

Descrição

workspace

Sim

ID do workspace ARMS.

serviceId

Sim

ID da aplicação ou service.

regionId

Sim

Região de acesso, como cn-hangzhou.

slsProject

Sim

Projeto do Simple Log Service que armazena os resultados do Live-Debug.

targetIp

Não

Endereço IP da instância alvo. Valor padrão: * (todas as instâncias).

Etapa 4: Usar linguagem natural para iniciar o diagnóstico

Ao descrever a necessidade de diagnóstico, inclua as seguintes informações (o Agent solicitará caso alguma esteja faltando):

Informação

Obrigatória

Exemplo

Local alvo

Sim

OrderService.create_order em app.service.order, ou a linha N de um arquivo específico.

Momento da observação

Recomendado

Entrada, saída, exceção ou linha específica (o padrão geralmente é a saída).

Conteúdo a observar

Sim

Parâmetros de entrada, valor de retorno, latência, variáveis locais ou pilha de chamadas.

Condição de filtro

Não

Apenas quando amount > 10000.

Duração ou contagem

Não

30 minutos, ou parar após 50 capturas.

Depois que a tarefa for criada, o Agent retornará um taskId. Compare com as configurações de referência em Reference configurations para verificar se os campos de módulo alvo, método, location, modelo ou capture estão corretos e, em seguida, acione o tráfego do service.

Etapa 5: Acionar tráfego, verificar resultados e limpar

  1. Verificar a configuração: Confirme se o taskConfig enviado pelo Agent corresponde às configurações de referência quanto ao local alvo e ao conteúdo da coleta.

  2. Acionar tráfego do service: Envie uma ou mais solicitações a uma interface que atinja o caminho de código alvo.

  3. Consultar resultados: Informe ao Agent:

    Query the collection results for the taskId from just now, and help me interpret whether the probe is installed and what was captured.
    • Status da Tarefa: Se a sonda foi instalada com sucesso, métricas de funil e outras informações de status.

    • Resultados da Captura: O conteúdo efetivamente coletado, como logs e snapshots.

  4. Limpar (execute sempre esta etapa):

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

Configurações de referência

Utilize as configurações de referência a seguir para validar o taskConfig gerado pelo Agent. Cada subseção corresponde a um tipo de sonda na tabela Supported diagnostics capabilities.

Log dinâmico (LOG)

Exemplo de comando:

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.

Configuração de referência: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
}

Nível de linha com condição:

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

Configuração de referência: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"
}

Snapshot de método (SNAPSHOT)

Exemplo de comando:

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.

Configuração de referência: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
}

Filtragem condicional com 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.

Configuração de referência: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 exceção:

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

Configuração de referência: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)

Exemplo de comando:

Add an amount histogram metric to create_order. Include a tag indicating whether the user is a VIP. Keep it for 1 hour.

Configuração de referência: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)

Exemplo de comando:

Temporarily add a span on OrderService.create_order named dyn.create_order. Include the order ID and amount as span attributes.

Configuração de referência: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"
}

Marcação de span (SPAN_TAG)

Exemplo de comando:

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

Configuração de referência: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"
}

Perguntas frequentes

O agent relata que o comando cms2 ou aliyun está indisponível

Causa: O Alibaba Cloud CLI não está instalado, a versão é muito antiga ou o binário do plugin aliyuncms2 não está pronto.

Solução:

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

Certifique-se de ter executado aliyun configure para configurar o par de AccessKey.

Tarefa criada com sucesso, mas nenhum resultado de captura aparece

Realize a solução de problemas na seguinte ordem:

  1. Peça ao Agent para verificar primeiro o Status da Tarefa e confirmar se a sonda foi instalada com sucesso.

  2. Verifique se typeName e methodName correspondem ao nome do módulo em tempo de execução e ao __qualname__. Verifique se o módulo principal deveria ser __main__.

  3. Confirme se você acionou uma solicitação que atinge a função alvo. Verifique se a condição de filtro não está restritiva demais.

  4. Confirme se o regionId em .arms-info corresponde à região do slsProject.

  5. Aumente a janela de tempo da consulta e tente novamente.

Você também pode dizer ao Agent: "Nenhum dado foi capturado. Ajude-me a verificar se o status e o local alvo estão corretos."

O SLS relata ProjectNotExist

Causa: A região usada para a consulta não corresponde à região do projeto do Simple Log Service.

Solução: Insira o regionId correto em .arms-info e certifique-se de que o Agent exportou a variável LIVE_DEBUG_REGION_ID. Não dependa apenas da região padrão da CLI.

Como confirmar que as sondas foram limpas

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

Ou peça ao Agent para fazer uma prévia de simulação (dry-run) antes de executar a limpeza.

Aplicações Python podem realizar diagnósticos de thread, memória ou descompilação?

Não. Esses são recursos de Comando suportados apenas para aplicações Java/JVM. Para aplicações Python, utilize diagnósticos de log, snapshot, métrica ou span.

Referências