Gerencia tarefas dinâmicas de probe de código para aplicações Python por meio da API ServiceTaskController do Cloud Monitor (CMS) (versão 2024-03-30). O recurso suporta cinco tipos de probe (LOG, SNAPSHOT, METRIC, SPAN e SPAN_TAG), e os resultados de captura são armazenados no Simple Log Service (SLS).
Pré-requisitos
Alibaba Cloud CLI — Os comandos
cms2eslsmencionados neste tópico exigem a Alibaba Cloud CLI (interface de linha de comando).Workspace ID — O ID do workspace do Application Real-Time Monitoring Service (ARMS), como
default-cms-xxx-cn-hangzhou.Service ID — O ID da aplicação ou service, como
ggxw4lnjuz@f2fd3a6265a254a052afb.Projeto SLS — O projeto SLS da aplicação, como
proj-xtrace-...-cn-hangzhou.Região — Especifique o parâmetro
--regionexplicitamente tanto para comandos CMS quanto SLS para evitar dependência da região padrão da CLI.
Este tópico abrange apenas aplicações Python (tarefas de Probe).
Operações de API
|
Operação |
Método HTTP |
Caminho |
Comando CLI |
|
Crie uma tarefa |
|
|
|
|
Listar tarefas |
|
|
|
|
Consultar uma tarefa |
|
|
|
|
Exclua uma tarefa |
|
|
|
|
Consultar resultados de captura |
SLS |
(Não é uma operação CMS) |
|
Parâmetros de caminho
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
O ID do workspace ARMS, como |
|
|
string |
Sim |
O ID da aplicação ou service, como |
|
|
string |
Sim (Get/Delete) |
O ID da tarefa retornado pela operação de criação. |
Parâmetros comuns da CLI
|
Parâmetro |
Descrição |
Padrão |
|
|
A região. Especifique este parâmetro explicitamente para comandos CMS e SLS para evitar dependência da região padrão da CLI. |
A região padrão na configuração da Alibaba Cloud CLI |
|
|
O endpoint do CMS. Substitui o endpoint derivado da região. |
|
|
|
Gera saída JSON indentada. O modo padrão |
|
CreateServiceTask
Crie uma tarefa de probe Live-Debug.
Solicitação
POST /serviceTask/{workspace}/{serviceId}/task
Content-Type: application/json
Parâmetros do corpo
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
O tipo de tarefa ( |
|
|
string |
Sim |
O endereço IP da instância alvo. Defina este parâmetro como |
|
|
string (texto JSON) |
Sim |
Um objeto de configuração simples de probe único. O servidor o armazena como string. O parâmetro da CLI |
Exemplo de CLI
aliyun cms2 apm service-task create \
--workspace <workspace> --service-id <serviceId> \
--type <taskType> --ip '<targetIp>' \
--task-config '<taskConfigJson>' \
--region <regionId> -o json
Para corresponder a todas as instâncias, defina
--ipcomo*.Passe um objeto JSON bruto para
--task-config. Não é necessário escapar o JSON manualmente.
Resposta
{
"success": true,
"data": {
"requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"taskId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
}
}
|
Campo |
Descrição |
|
|
O ID da solicitação. |
|
|
O ID da tarefa. Utilize este valor para consultas SLS e operações Get e Delete. |
Exemplo de corpo HTTP (após serialização da CLI)
{
"type": "live_debug_log_probe",
"ip": "*",
"taskConfig": "{\"probeType\":\"LOG\",\"language\":\"python\",\"target\":{\"typeName\":\"app.service.order\",\"methodName\":\"OrderService.create_order\",\"location\":\"exit\",\"instanceIds\":[\"*\"]},\"action\":{\"type\":\"LOG\",\"template\":\"id={order_id}\"},\"ttl\":\"30m\",\"captureCount\":100}"
}
No corpo HTTP, taskConfig é uma string JSON escapada. Ao passar o parâmetro pela CLI via --task-config, passe o objeto JSON sem escapes. A CLI cuida da serialização.
ListServiceTask
Lista as tarefas de probe Live-Debug.
Solicitação
GET /serviceTask/{workspace}/{serviceId}/tasks?type={taskType}&maxResults={n}
Parâmetros de consulta
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
O tipo de tarefa para filtragem por correspondência exata, como |
|
|
int |
Não |
O número máximo de entradas a retornar. Valor padrão: |
Campos de resposta
A CLI gera um array data.serviceTasks[]. Cada item contém os seguintes campos:
|
Campo |
Descrição |
|
|
O ID da tarefa. |
|
|
O tipo da tarefa. |
|
|
O ID do service. |
|
|
O endereço IP especificado durante a criação, ou |
|
|
O momento em que a tarefa foi criada. |
|
|
O momento da última atualização da tarefa. |
|
|
A configuração da tarefa (objeto de probe simples). |
Exemplo de CLI
aliyun cms2 apm service-task list \
--workspace <workspace> --service-id <serviceId> \
--type <taskType> --max-results 100 \
--region <regionId> -o json
GetServiceTask
Consulta os detalhes de uma única tarefa de probe Live-Debug.
Solicitação
GET /serviceTask/{workspace}/{serviceId}/task/{taskId}?type={taskType}
Parâmetros de consulta
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
O tipo da tarefa. Deve corresponder ao tipo real da tarefa. |
Resposta
A CLI gera um objeto data.serviceTask. Os campos são idênticos aos de um único item na resposta de Listagem.
Exemplo de CLI
aliyun cms2 apm service-task get \
--workspace <workspace> --service-id <serviceId> \
--task-id <taskId> --type <taskType> \
--region <regionId> -o json
DeleteServiceTask
Exclua uma tarefa de probe Live-Debug. Após a exclusão, o servidor remove a tarefa e sincroniza a alteração com o servidor de configuração. O probe correspondente no lado do agente torna-se inativo.
Para desativar um probe implantado, exclua a tarefa correspondente.
Solicitação
DELETE /serviceTask/{workspace}/{serviceId}/task/{taskId}?type={taskType}
Parâmetros de consulta
|
Parâmetro |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
O tipo da tarefa. Deve corresponder ao tipo real da tarefa. |
Exemplo de CLI
aliyun cms2 apm service-task delete \
--workspace <workspace> --service-id <serviceId> \
--task-id <taskId> --type <taskType> \
--region <regionId> -o json
Exemplo de exclusão em lote
Para excluir todas as tarefas de probe de um service, liste e exclua as tarefas para cada um dos cinco tipos de probe:
WS=<workspace>; SVC=<serviceId>; REGION=<regionId>
for t in live_debug_log_probe live_debug_snapshot_probe \
live_debug_metric_probe live_debug_span_probe live_debug_span_tag_probe; do
aliyun cms2 apm service-task list \
--workspace "$WS" --service-id "$SVC" --type "$t" --region "$REGION" -o json |
python3 -c 'import sys,json; [print(t["taskId"]) for t in (json.load(sys.stdin)["data"].get("serviceTasks") or [])]' |
while read -r id; do
aliyun cms2 apm service-task delete \
--workspace "$WS" --service-id "$SVC" \
--task-id "$id" --type "$t" --region "$REGION" -o json
done
done
Consultar resultados de captura (SLS)
O status e os resultados de captura são gravados no Simple Log Service (SLS) e não são retornados pela operação Get do CMS.
Exemplo de CLI
Consulte dados dos últimos 10 minutos. Substitua <taskId> pelo ID da tarefa retornado na operação de criação.
FROM=$(( $(date +%s) - 600 )); TO=$(date +%s)
# Task status (installation status, funnel metrics)
aliyun sls get-logs-v2 --region <regionId> --accept-encoding gzip \
--project <slsProject> --logstore logstore-apm-logs \
--from "$FROM" --to "$TO" \
--query "* and \"<taskId>\" | SELECT content FROM log WHERE json_extract_scalar(attributes, '\$[\"livedebug.report_type\"]') = 'status'"
# Capture results (actual captured data)
aliyun sls get-logs-v2 --region <regionId> --accept-encoding gzip \
--project <slsProject> --logstore logstore-apm-logs \
--from "$FROM" --to "$TO" \
--query "* and \"<taskId>\" | SELECT content FROM log WHERE json_extract_scalar(attributes, '\$[\"livedebug.report_type\"]') != 'status'"
Parâmetros de consulta
|
Parâmetro |
Obrigatório |
Descrição |
|
|
Sim |
O projeto SLS da aplicação, como |
|
|
Sim |
O nome do logstore. Valor padrão: |
|
|
Sim |
O intervalo de tempo da consulta em timestamps Unix (segundos). |
|
|
Sim |
A região do projeto SLS. Deve corresponder à região do projeto. Especifique este parâmetro explicitamente. |
Tipos de consulta
|
Tipo de consulta |
Condição de filtro |
Descrição |
|
Status da tarefa |
|
Status de instalação e métricas de funil. |
|
Resultados de captura |
|
Dados capturados efetivamente. |
Os projetos SLS são isolados por região. Um parâmetro region incorreto causa o erro ProjectNotExist.
Enumeração de tipos de tarefa
A tabela a seguir lista os cinco tipos de probe suportados para aplicações Python. A convenção de nomenclatura é live_debug_ + semântica do probe em minúsculas + _probe.
|
taskType |
Tipo de probe |
Descrição |
|
|
LOG |
Gera logs dinâmicos no ponto alvo. |
|
|
SNAPSHOT |
Captura snapshots de métodos e serializa o grafo de objetos. |
|
|
METRIC |
Emite métricas personalizadas no ponto alvo. |
|
|
SPAN |
Crie um span OpenTelemetry para a execução da função. |
|
|
SPAN_TAG |
Adiciona atributos ao span ativo atual. |
Estrutura taskConfig do probe
O objeto simples passado para --task-config:
{
"probeType": "LOG|SNAPSHOT|METRIC|SPAN|SPAN_TAG",
"language": "python",
"target": { },
"action": { },
"trigger": { },
"rateLimit": { },
"ttl": "1h",
"captureCount": 100,
"enabled": true
}
Campos de nível superior
|
Campo |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
O tipo de probe. Valores válidos: |
|
|
string |
Sim |
A linguagem. Defina este parâmetro como |
|
|
object |
Sim |
Localiza o método ou linha alvo. |
|
|
object |
Sim |
A ação do probe. A estrutura varia conforme o |
|
|
object |
Não |
A condição de gatilho. |
|
|
object |
Não |
Configuração de limitação de taxa. |
|
|
string |
Pelo menos um entre |
O tempo de vida. Formatos suportados: |
|
|
int |
Pelo menos um entre |
O número máximo de capturas. A tarefa termina quando |
|
|
boolean |
Não |
Geralmente |
target — localizar o alvo
|
Campo |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Recomendado para probes no nível de função |
O nome do módulo (chave em |
|
|
string |
Recomendado para probes no nível de função |
O |
|
|
string |
Não (recomendado para probes no nível de linha) |
O nome do arquivo-fonte ou sufixo do caminho. |
|
|
string |
Não |
O ponto de hook. Valores válidos: |
|
|
string[] |
Altamente recomendado |
A lista de IDs de instância onde o probe terá efeito. Coloque este parâmetro dentro de |
|
|
string[] |
Não |
A lista de endereços IP onde o probe terá efeito. Combinado com |
Probes no nível de linha podem basear-se principalmente em sourceFile + location:"line:N".
trigger — condição de gatilho (opcional)
|
Campo |
Tipo |
Padrão |
Descrição |
|
|
string |
- |
O probe captura dados apenas quando esta expressão for avaliada como verdadeira. |
|
|
string |
- |
Filtro de chamador (raramente usado em Python). |
Exemplos de condição: amount > 10000 ou @return is None or amount > 10000
Regras de expressão:
Utilize nomes de parâmetros, variáveis locais ou variáveis globais no nível do módulo diretamente.
Nas localizações
exitouexception, use@return,@duration(milissegundos) ou@exception.Não utilize OGNL,
args[0],returnValueoudurationMs.Se a condição referenciar
@returnou@exception, alocationdo probe deve serexitouexception.
rateLimit — limitação de taxa (opcional)
|
Campo |
Tipo |
Padrão |
Descrição |
|
|
int |
Varia conforme o tipo de probe (veja abaixo) |
O máximo de execuções por segundo (token bucket). |
|
|
double |
1.0 |
A probabilidade aleatória de passagem (0 a 1). |
|
|
int |
100 |
O tempo limite para uma única captura, em milissegundos. |
Limites de taxa padrão: probes LOG, METRIC, SPAN e SPAN_TAG permitem aproximadamente 5.000 execuções por segundo. Probes SNAPSHOT permitem aproximadamente 1 execução por segundo. Probes no nível de linha possuem um limite global de proteção adicional de aproximadamente 100 execuções por segundo.
Ação do probe por tipo
LOG (taskType: live_debug_log_probe)
Gera logs dinâmicos no ponto alvo sem serialização do grafo de objetos.
Campos de action
|
Campo |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
Defina como |
|
|
string |
Sim |
O modelo de log. Use a sintaxe |
Probes LOG apenas renderizam o modelo e ignoram a dimensão capture. Para capturar parâmetros, valores de retorno ou rastreamentos de pilha, utilize um probe SNAPSHOT.
Exemplo
{
"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
}
SNAPSHOT (taskType: live_debug_snapshot_probe)
Captura snapshots de métodos e serializa o grafo de objetos.
Campos de action
|
Campo |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
Defina como |
|
|
string[] |
Sim |
As dimensões de captura. Se não fornecido ou definido como |
|
|
string[] |
Não |
Expressões adicionais a serem avaliadas. |
|
|
object |
Não |
Limites de serialização do grafo de objetos. |
Valores enum de capture
|
Valor |
Descrição |
|
|
Serializa os argumentos do método. |
|
|
Serializa o valor de retorno. |
|
|
Serializa a instância atual. |
|
|
Registra o resumo da exceção. |
|
|
Captura variáveis locais (requer informações de depuração). |
|
|
Captura a pilha de chamadas (opt-in, deve ser incluído explicitamente). |
|
|
Agrega subchamadas dentro do corpo do método. |
captureConfig
|
Campo |
Padrão |
Descrição |
|
|
3 |
A profundidade máxima de serialização de objetos. |
|
|
100 |
O número máximo de elementos em coleções ou arrays. |
|
|
1024 |
O comprimento máximo de strings. |
|
|
50 |
O número máximo de campos por objeto. |
|
|
65536 |
O tamanho máximo de um único snapshot em bytes. |
|
|
50 |
A profundidade máxima da pilha de chamadas. |
|
|
|
Expressões regulares para ocultação de nomes de campos. |
captureExpressions
A sintaxe é a mesma de trigger.condition e modelos LOG (eval limitado). Os resultados são gravados em context.evaluatedExpressions. Cada item possui o seguinte formato:
{"name": "order_id", "type": "...", "value": "...", "notCapturedReason": null}
Se a avaliação falhar, value é definido como null e notCapturedReason registra o motivo. Isso não afeta outras dimensões. captureExpressions e capture são independentes entre si.
Exemplo
{
"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"],
"captureConfig": {
"maxDepth": 3,
"maxCollectionSize": 100,
"maxStringLength": 1024
}
},
"ttl": "30m",
"captureCount": 50
}
METRIC (taskType: live_debug_metric_probe)
Emite métricas personalizadas no ponto alvo.
Campos de action
|
Campo |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
Defina como |
|
|
string |
Sim |
O nome da métrica, como |
|
|
string |
Sim |
O tipo da métrica. Valores válidos: |
|
|
string |
Sim |
Uma expressão Python que resulta no valor da métrica. |
|
|
object |
Não |
Um mapa de tags. Os valores são strings de expressão Python. |
Exemplo
{
"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 (taskType: live_debug_span_probe)
Crie um span OpenTelemetry para a execução da função alvo. Marca o span como ERROR e registra um evento de exceção caso ocorra uma exceção. Apenas no nível de função.
Campos de action
|
Campo |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
Defina como |
|
|
string |
Sim |
O nome do span. |
|
|
object |
Não |
Um mapa de atributos. Os valores são strings de expressão Python. |
Exemplo
{
"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"
}
SPAN_TAG (taskType: live_debug_span_tag_probe)
Adiciona atributos ao span ativo atual. Ignora silenciosamente se não existir nenhum span ativo.
Campos de action
|
Campo |
Tipo |
Obrigatório |
Descrição |
|
|
string |
Sim |
Defina como |
|
|
array |
Sim |
Um array de tags. Cada item tem o formato |
Exemplo
{
"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"
}
Erros e solução de problemas
|
Sintoma |
Causa possível |
Solução |
|
|
A região do SLS está incorreta. |
Especifique a região correta usando |
|
A listagem retorna resultados vazios, mas a tarefa existe |
O parâmetro |
Liste as tarefas pelo tipo exato da tarefa. |
|
Crie uma tarefa com |
Este parâmetro não afeta tarefas já implantadas. |
Use |
|
O probe não captura dados |
|
Defina |
|
A criação de SPAN falha ou é inválida |
|
Altere para nível de função com |
|
Exceção de TTL |
A unidade |
Use |
Exemplo completo de fluxo de trabalho (probe LOG)
# 0. Environment variables
REGION=cn-hangzhou
SLS_PROJECT=proj-xtrace-xxxxxxxxxxxxxxxxxxxxxx-cn-hangzhou
WORKSPACE=default-cms-xxxxxxxxxxxxxxxxxx-cn-hangzhou
SERVICE_ID='ggxw4lnjuz@f2fd3a6265a254a052afb'
# 1. Create a task
RESP=$(aliyun cms2 apm service-task create \
--workspace "$WORKSPACE" --service-id "$SERVICE_ID" \
--type live_debug_log_probe --ip '*' \
--task-config '{"probeType":"LOG","language":"python","target":{"typeName":"app.service.order","methodName":"OrderService.create_order","location":"exit","instanceIds":["*"]},"action":{"type":"LOG","template":"id={order_id} ret={@return}"},"ttl":"30m","captureCount":50}' \
--region "$REGION" -o json)
echo "$RESP"
TASK_ID=$(echo "$RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["taskId"])')
# 2. Verify the task
aliyun cms2 apm service-task get \
--workspace "$WORKSPACE" --service-id "$SERVICE_ID" \
--task-id "$TASK_ID" --type live_debug_log_probe \
--region "$REGION" -o json
# 3. Generate traffic to the instrumented endpoint and query results (last 10 minutes)
FROM=$(( $(date +%s) - 600 )); TO=$(date +%s)
aliyun sls get-logs-v2 --region "$REGION" --accept-encoding gzip \
--project "$SLS_PROJECT" --logstore logstore-apm-logs \
--from "$FROM" --to "$TO" \
--query "* and \"$TASK_ID\" | SELECT content FROM log WHERE json_extract_scalar(attributes, '\$[\"livedebug.report_type\"]') != 'status'"
# 5. Delete the task
aliyun cms2 apm service-task delete \
--workspace "$WORKSPACE" --service-id "$SERVICE_ID" \
--task-id "$TASK_ID" --type live_debug_log_probe \
--region "$REGION" -o json