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.
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 |
|
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 |
|
Captura ARGS, RETURN, LOCALS, STACK e outros dados. |
|
Métrica dinâmica |
METRIC |
|
Suporta os tipos de métrica COUNTER, GAUGE, HISTOGRAM e SUMMARY. |
|
Span dinâmico |
SPAN |
|
Cria um span OTel no nível da função. |
|
Marcação de span |
SPAN_TAG |
|
Acrescenta atributos ao span ativo atual. |
Fluxo de trabalho
Veja como o Skill orquestra uma sessão de diagnóstico:
Descreva a necessidade de diagnóstico (qual função observar, o que capturar e, opcionalmente, condições de filtro e duração).
O Agent verifica o ambiente da interface de linha de comando (CLI) e lê o arquivo
.arms-info(solicita-o caso esteja ausente).O Agent gera uma configuração de sonda, cria a tarefa e retorna um
taskId.Acione o tráfego do service relevante.
O Agent consulta o status de instalação e os resultados da coleta e os interpreta.
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 |
|
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 |
|
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.
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
Obtenha o pacote de instalação do Live-Debug Agent Skill ou a entrada no marketplace (inclui as especificações de operação
SKILL.mde os scripts auxiliares emscripts/).Siga as instruções da sua ferramenta de IA para instalar o Skill no QoderWork, Cursor, Claude Code ou outro ambiente.
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 |
|
|
Sim |
ID do workspace ARMS. |
|
|
Sim |
ID da aplicação ou service. |
|
|
Sim |
Região de acesso, como |
|
|
Sim |
Projeto do Simple Log Service que armazena os resultados do Live-Debug. |
|
|
Não |
Endereço IP da instância alvo. Valor padrão: |
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 |
|
|
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 |
|
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
Verificar a configuração: Confirme se o
taskConfigenviado pelo Agent corresponde às configurações de referência quanto ao local alvo e ao conteúdo da coleta.Acionar tráfego do service: Envie uma ou mais solicitações a uma interface que atinja o caminho de código alvo.
-
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.
-
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:
Peça ao Agent para verificar primeiro o Status da Tarefa e confirmar se a sonda foi instalada com sucesso.
Verifique se
typeNameemethodNamecorrespondem ao nome do módulo em tempo de execução e ao__qualname__. Verifique se o módulo principal deveria ser__main__.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.
Confirme se o
regionIdem.arms-infocorresponde à região doslsProject.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.