Cloud Monitor：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"
}