Live-Debug ServiceTask API 参考

路径参数（Path）

公共 CLI 参数

请求

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

Body 参数

调用示例：

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

• 匹配全部实例时 --ip 传 *。

• --task-config 直接传原始 JSON 对象，无需手动二次转义。

响应（CLI 输出）

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

Body 示例（CLI 拼装后的 HTTP 形态）

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

HTTP Body 里 taskConfig 是转义后的 JSON 字符串；向 CLI --task-config 传参时传未转义的对象 JSON 即可，转义由 CLI 完成。

请求

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

Query 参数

响应字段

CLI 输出 data.serviceTasks[] 数组，每项常见字段：

调用示例：

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

请求

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

Query 参数

响应

CLI 输出 data.serviceTask 对象，字段同 List 单项。

调用示例：

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

请求

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

Query 参数

删除后服务端移除任务并 syncToConfigServer，Agent 侧对应探针随之失效。这是停用已下发探针的正确方式。

调用示例：

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

批量清空某服务下全部 Probe（List 按 type 精确过滤，需对五种 probe type 逐个 list + delete）：

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

Probe（代码增强）

命名规则：live_debug_ + 探针语义小写 + _probe。五种探针 Python 均支持。

顶层字段

target — 定位目标

行级探针可主要依赖 sourceFile + location:"line:N"。

trigger — 触发条件（可选）

条件示例：amount > 10000 或 @return is None or amount > 10000

表达式规则：

• 直接使用参数名/局部变量/模块全局变量。

• exit / exception 可用 @return、@duration（毫秒）、@exception。

• 不要使用 OGNL、args[0]、returnValue、durationMs。

• 若条件引用 @return / @exception，探针 location 必须是 exit 或 exception。

rateLimit — 速率控制（可选）

默认限流：LOG/METRIC/SPAN/SPAN_TAG 约 5000 次/秒，SNAPSHOT 约 1 次/秒；行级探针另有全局约 100 次/秒保护。

LOG（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
}

SNAPSHOT（taskType: live_debug_snapshot_probe）

采集方法快照并做对象图序列化上报。

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

在目标点生成自定义指标，写入监控系统。

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

在目标函数执行期间新建 OTel Span；异常时标记 ERROR 并记录 exception event。仅函数级。

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

给当前活跃 Span 追加属性；无活跃 Span 时静默跳过。

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