Todos os produtos
Search
Central de documentação

Cloud Monitor:Referência da API ServiceTask de Live-Debug

Última atualização: Aug 03, 2026

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 cms2 e sls mencionados 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 --region explicitamente tanto para comandos CMS quanto SLS para evitar dependência da região padrão da CLI.

Nota

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

POST

/serviceTask/{workspace}/{serviceId}/task

aliyun cms2 apm service-task create

Listar tarefas

GET

/serviceTask/{workspace}/{serviceId}/tasks

aliyun cms2 apm service-task list

Consultar uma tarefa

GET

/serviceTask/{workspace}/{serviceId}/task/{taskId}

aliyun cms2 apm service-task get

Exclua uma tarefa

DELETE

/serviceTask/{workspace}/{serviceId}/task/{taskId}

aliyun cms2 apm service-task delete

Consultar resultados de captura

SLS get-logs-v2

(Não é uma operação CMS)

aliyun sls get-logs-v2

Parâmetros de caminho

Parâmetro

Tipo

Obrigatório

Descrição

workspace

string

Sim

O ID do workspace ARMS, como default-cms-xxx-cn-hangzhou.

serviceId

string

Sim

O ID da aplicação ou service, como ggxw4lnjuz@f2fd3a6265a254a052afb.

taskId

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

--region

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

--endpoint

O endpoint do CMS. Substitui o endpoint derivado da região.

cms.${regionId}.aliyuncs.com

-o json

Gera saída JSON indentada. O modo padrão text gera JSON compacto em linha única.

text

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

type

string

Sim

O tipo de tarefa (taskType). Para valores válidos, consulte Task type enum.

ip

string

Sim

O endereço IP da instância alvo. Defina este parâmetro como * para corresponder a todas as instâncias.

taskConfig

string (texto JSON)

Sim

Um objeto de configuração simples de probe único. O servidor o armazena como string. O parâmetro da CLI --task-config aceita um objeto JSON bruto e o serializa automaticamente para string.

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 --ip como *.

  • 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

data.requestId

O ID da solicitação.

data.taskId

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}"
}
Nota

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

type

string

Sim

O tipo de tarefa para filtragem por correspondência exata, como live_debug_log_probe.

maxResults

int

Não

O número máximo de entradas a retornar. Valor padrão: 100. Valor máximo: 100.

Campos de resposta

A CLI gera um array data.serviceTasks[]. Cada item contém os seguintes campos:

Campo

Descrição

taskId

O ID da tarefa.

type

O tipo da tarefa.

serviceId

O ID do service.

ip

O endereço IP especificado durante a criação, ou *.

createTime

O momento em que a tarefa foi criada.

updateTime

O momento da última atualização da tarefa.

taskConfig

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

type

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.

Importante

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

type

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

--project

Sim

O projeto SLS da aplicação, como proj-xtrace-...-cn-hangzhou.

--logstore

Sim

O nome do logstore. Valor padrão: logstore-apm-logs.

--from / --to

Sim

O intervalo de tempo da consulta em timestamps Unix (segundos).

--region

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

livedebug.report_type = 'status'

Status de instalação e métricas de funil.

Resultados de captura

livedebug.report_type != 'status'

Dados capturados efetivamente.

Importante

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

live_debug_log_probe

LOG

Gera logs dinâmicos no ponto alvo.

live_debug_snapshot_probe

SNAPSHOT

Captura snapshots de métodos e serializa o grafo de objetos.

live_debug_metric_probe

METRIC

Emite métricas personalizadas no ponto alvo.

live_debug_span_probe

SPAN

Crie um span OpenTelemetry para a execução da função.

live_debug_span_tag_probe

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

probeType

string

Sim

O tipo de probe. Valores válidos: LOG, SNAPSHOT, METRIC, SPAN, SPAN_TAG.

language

string

Sim

A linguagem. Defina este parâmetro como python.

target

object

Sim

Localiza o método ou linha alvo.

action

object

Sim

A ação do probe. A estrutura varia conforme o probeType.

trigger

object

Não

A condição de gatilho.

rateLimit

object

Não

Configuração de limitação de taxa.

ttl

string

Pelo menos um entre ttl ou captureCount

O tempo de vida. Formatos suportados: 30s, 5m, 2h, 1d ou um número em segundos. Não utilize ms.

captureCount

int

Pelo menos um entre ttl ou captureCount

O número máximo de capturas. A tarefa termina quando ttl ou captureCount for atingido primeiro.

enabled

boolean

Não

Geralmente true na criação. Crie uma tarefa com enabled: false não desativa um probe existente.

target — localizar o alvo

Campo

Tipo

Obrigatório

Descrição

typeName

string

Recomendado para probes no nível de função

O nome do módulo (chave em sys.modules), como app.service.order. Defina este parâmetro como __main__ para o módulo principal.

methodName

string

Recomendado para probes no nível de função

O __qualname__ da função. Para métodos de classe, use o formato ClassName.method_name. Para funções simples, use diretamente o nome da função.

sourceFile

string

Não (recomendado para probes no nível de linha)

O nome do arquivo-fonte ou sufixo do caminho.

location

string

Não

O ponto de hook. Valores válidos: enter, exit, exception, line:N. Valor padrão: exit. Probes SPAN suportam apenas o nível de função e não podem usar line.

instanceIds

string[]

Altamente recomendado

A lista de IDs de instância onde o probe terá efeito. Coloque este parâmetro dentro de target, não no nível superior de taskConfig. Defina como ["*"] para todas as instâncias. Se estiver vazio, o probe não terá efeito.

instanceIps

string[]

Não

A lista de endereços IP onde o probe terá efeito. Combinado com instanceIds usando lógica AND.

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

condition

string

-

O probe captura dados apenas quando esta expressão for avaliada como verdadeira.

callerPattern

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 exit ou exception, use @return, @duration (milissegundos) ou @exception.

  • Não utilize OGNL, args[0], returnValue ou durationMs.

  • Se a condição referenciar @return ou @exception, a location do probe deve ser exit ou exception.

rateLimit — limitação de taxa (opcional)

Campo

Tipo

Padrão

Descrição

maxExecutionsPerSecond

int

Varia conforme o tipo de probe (veja abaixo)

O máximo de execuções por segundo (token bucket).

samplingProbability

double

1.0

A probabilidade aleatória de passagem (0 a 1).

executionTimeoutMs

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

type

string

Sim

Defina como "LOG".

template

string

Sim

O modelo de log. Use a sintaxe {expression} para valores dinâmicos.

Nota

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

type

string

Sim

Defina como "SNAPSHOT".

capture

string[]

Sim

As dimensões de captura. Se não fornecido ou definido como [], nenhum grafo de objetos será capturado.

captureExpressions

string[]

Não

Expressões adicionais a serem avaliadas.

captureConfig

object

Não

Limites de serialização do grafo de objetos.

Valores enum de capture

Valor

Descrição

ARGS

Serializa os argumentos do método.

RETURN

Serializa o valor de retorno.

THIS

Serializa a instância atual.

EXCEPTION

Registra o resumo da exceção.

LOCALS

Captura variáveis locais (requer informações de depuração).

STACK

Captura a pilha de chamadas (opt-in, deve ser incluído explicitamente).

EXECUTION_DETAIL

Agrega subchamadas dentro do corpo do método.

captureConfig

Campo

Padrão

Descrição

maxDepth

3

A profundidade máxima de serialização de objetos.

maxCollectionSize

100

O número máximo de elementos em coleções ou arrays.

maxStringLength

1024

O comprimento máximo de strings.

maxFieldCount

50

O número máximo de campos por objeto.

maxTotalSizeBytes

65536

O tamanho máximo de um único snapshot em bytes.

stackTraceDepth

50

A profundidade máxima da pilha de chamadas.

redactedFieldPatterns

[".*password.*",".*token.*",".*secret.*"]

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

type

string

Sim

Defina como "METRIC".

metricName

string

Sim

O nome da métrica, como livedebug.order.amount.

metricType

string

Sim

O tipo da métrica. Valores válidos: COUNTER, GAUGE, HISTOGRAM, SUMMARY.

valueExpression

string

Sim

Uma expressão Python que resulta no valor da métrica.

tags

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

type

string

Sim

Defina como "SPAN".

spanName

string

Sim

O nome do span.

spanTags

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

type

string

Sim

Defina como "SPAN_TAG".

tags

array

Sim

Um array de tags. Cada item tem o formato { "key": "...", "value": "<Python expression>" }.

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

ProjectNotExist

A região do SLS está incorreta.

Especifique a região correta usando aliyun sls --region. A região deve corresponder à região do projeto.

A listagem retorna resultados vazios, mas a tarefa existe

O parâmetro type não corresponde ao tipo real da tarefa.

Liste as tarefas pelo tipo exato da tarefa.

Crie uma tarefa com enabled:false não interrompe um probe ativo

Este parâmetro não afeta tarefas já implantadas.

Use DeleteServiceTask para desativar probes.

O probe não captura dados

instanceIds está vazio, o nome do módulo está incorreto ou nenhum tráfego foi acionado.

Defina instanceIds como ["*"], verifique typeName e methodName e gere tráfego antes de consultar o status.

A criação de SPAN falha ou é inválida

line:N foi usado como localização.

Altere para nível de função com enter ou exit.

Exceção de TTL

A unidade ms foi utilizada.

Use s, m, h, d ou um número em segundos.

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