Cloud Monitor:Live-Debug ServiceTask API reference

Path parameters

Common CLI parameters

Request

POST /serviceTask/{workspace}/{serviceId}/task
Content-Type: application/json

Body parameters

CLI example

aliyun cms2 apm service-task create \
  --workspace <workspace> --service-id <serviceId> \
  --type <taskType> --ip '<targetIp>' \
  --task-config '<taskConfigJson>' \
  --region <regionId> -o json

• To match all instances, set --ip to *.

• Pass a raw JSON object to --task-config. You do not need to escape the JSON manually.

Response

{
  "success": true,
  "data": {
    "requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "taskId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
  }
}

HTTP body example (after CLI serialization)

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

Request

GET /serviceTask/{workspace}/{serviceId}/tasks?type={taskType}&maxResults={n}

Query parameters

Response fields

The CLI outputs a data.serviceTasks[] array. Each item contains the following fields:

CLI example

aliyun cms2 apm service-task list \
  --workspace <workspace> --service-id <serviceId> \
  --type <taskType> --max-results 100 \
  --region <regionId> -o json

Request

GET /serviceTask/{workspace}/{serviceId}/task/{taskId}?type={taskType}

Query parameters

Response

The CLI outputs a data.serviceTask object. The fields are the same as a single item in the List response.

CLI example

aliyun cms2 apm service-task get \
  --workspace <workspace> --service-id <serviceId> \
  --task-id <taskId> --type <taskType> \
  --region <regionId> -o json

Request

DELETE /serviceTask/{workspace}/{serviceId}/task/{taskId}?type={taskType}

Query parameters

CLI example

aliyun cms2 apm service-task delete \
  --workspace <workspace> --service-id <serviceId> \
  --task-id <taskId> --type <taskType> \
  --region <regionId> -o json

Batch deletion example

To delete all probe tasks for a service, list and delete tasks for each of the five probe types:

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

CLI example

Query data from the last 10 minutes. Replace <taskId> with the task ID returned by the create operation.

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'"

Query parameters

Query types

Top-level fields

target — locate the target

Line-level probes can primarily rely on sourceFile + location:"line:N".

trigger — trigger condition (optional)

Condition examples:amount > 10000 or @return is None or amount > 10000

Expression rules:

• Use parameter names, local variables, or module-level global variables directly.

• At exit or exception locations, use @return, @duration (milliseconds), or @exception.

• Do not use OGNL, args[0], returnValue, or durationMs.

• If the condition references @return or @exception, the probe location must be exit or exception.

rateLimit — rate limiting (optional)

Default rate limits: LOG, METRIC, SPAN, and SPAN_TAG probes allow approximately 5,000 executions per second. SNAPSHOT probes allow approximately 1 execution per second. Line-level probes have an additional global protection limit of approximately 100 executions per second.

LOG (taskType: live_debug_log_probe)

Outputs dynamic logs at the target point without object graph serialization.

{
  "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)

Captures method snapshots and serializes the object graph.

{"name": "order_id", "type": "...", "value": "...", "notCapturedReason": null}

{
  "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)

Emits custom metrics at the target point.

{
  "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)

Creates an OpenTelemetry span for the target function execution. Marks the span as ERROR and records an exception event if an exception occurs. Function-level only.

{
  "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)

Appends attributes to the current active span. Silently skips if no active span exists.

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