Cloud Monitor：通過 Live-Debug Agent Skill 診斷 Python 應用

支援的診斷能力

安裝 CLI

若尚未安裝，請參考安裝阿里雲 CLI（按本機作業系統選擇 Linux/macOS/Windows 安裝方式）。

安裝完成後確認可用：

aliyun version

配置訪問憑證

aliyun configure

按提示填寫 AccessKey ID、AccessKey Secret 與預設地區。建議使用 RAM 子帳號，並授予 CMS ServiceTask 與目標 SLS Project 的讀寫/查詢許可權。詳細說明請參考配置與管理身份憑證。

安裝 CMS CLI（aliyuncms2）並驗證 cms2 與 SLS 可用

CMS ServiceTask 能力由 aliyuncms2 外掛程式二進位提供：擷取 aliyuncms2 後放入 ~/.aliyun/ 目錄（或 PATH），即可通過 aliyun cms2 調用，憑證複用 aliyun configure 的配置。

# 驗證 CMS ServiceTask 相關能力
aliyun cms2 apm service-task --help

# 驗證 SLS 查詢可用
aliyun sls --help

若 cms2 不可用，請確認 aliyuncms2 二進位已放入 ~/.aliyun/（或 PATH）且具有可執行許可權：

ls -l ~/.aliyun/aliyuncms2
chmod +x ~/.aliyun/aliyuncms2
aliyun cms2 apm service-task --help

仍失敗時，請升級阿里雲 CLI 後重試：

aliyun upgrade -y

1. 動態日誌（LOG）

可以這樣說：

請使用 /alibabacloud-livedebug 技能，給 app.service.order 模組的 OrderService.create_order 出口打一條動態日誌，列印 order_id、amount、傳回值和耗時，保留半小時。

參考配置：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
}

行級、帶條件：

在 app/service/order.py 第 42 行打日誌，只有 amount >= 1000 時才輸出訂單號和金額。

參考配置：taskType = live_debug_log_probe

{
  "probeType": "LOG",
  "language": "python",
  "target": {
    "sourceFile": "app/service/order.py",
    "location": "line:42",
    "instanceIds": ["*"]
  },
  "trigger": {
    "condition": "amount >= 1000"
  },
  "action": {
    "type": "LOG",
    "template": "big order id={order_id} amount={amount}"
  },
  "ttl": "30m"
}

2. 方法快照（SNAPSHOT）

可以這樣說：

請使用 /alibabacloud-livedebug 技能，對 OrderService.create_order 出口做一次快照，採集入參、局部變數、傳回值和調用棧，最多采 20 次。

參考配置：taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.order",
    "methodName": "OrderService.create_order",
    "location": "exit",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS", "LOCALS", "RETURN", "STACK"],
    "captureConfig": {
      "maxDepth": 3,
      "maxCollectionSize": 100,
      "maxStringLength": 1024
    }
  },
  "ttl": "30m",
  "captureCount": 20
}

條件過濾 + 自訂欄位：

create_order 出口做快照：僅當傳回值為空白或金額大於 10000 時觸發；重點看 order_id、amount * count、self.user_id 和傳回值。

參考配置：taskType = live_debug_snapshot_probe

{
  "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"
    ]
  },
  "ttl": "30m",
  "captureCount": 50
}

異常現場：

PaymentService.process_payment 一旦拋異常就抓快照，帶上入參、異常資訊和調用棧，保留 2 小時。

參考配置：taskType = live_debug_snapshot_probe

{
  "probeType": "SNAPSHOT",
  "language": "python",
  "target": {
    "typeName": "app.service.payment",
    "methodName": "PaymentService.process_payment",
    "location": "exception",
    "instanceIds": ["*"]
  },
  "action": {
    "type": "SNAPSHOT",
    "capture": ["ARGS", "EXCEPTION", "STACK", "LOCALS"]
  },
  "ttl": "2h",
  "captureCount": 100
}

3. 動態指標（METRIC）

可以這樣說：

請使用 /alibabacloud-livedebug 技能，給 create_order 掛一個金額長條圖指標，標籤裡標一下是不是 vip 使用者，持續 1 小時。

參考配置：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"
}

4. 動態 Span（SPAN）

可以這樣說：

請使用 /alibabacloud-livedebug 技能，在 OrderService.create_order 上臨時加一個 Span，名叫 dyn.create_order，把訂單號和金額打到屬性裡。

參考配置：taskType = live_debug_span_probe

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

5. Span 打標（SPAN_TAG）

可以這樣說：

create_order 出口時，請使用 /alibabacloud-livedebug 技能，給當前 Span 打上 order.id 和 order.result（用傳回值），不要建立 Span。

參考配置：taskType = live_debug_span_tag_probe

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

Agent 提示 cms2/aliyun 命令不可用

原因： 未安裝阿里雲 CLI、版本過低，或 aliyuncms2 外掛程式二進位未就緒。

解決方案：

aliyun version
aliyun upgrade -y
ls -l ~/.aliyun/aliyuncms2   # 確認 CMS CLI 外掛程式二進位存在且可執行
aliyun cms2 apm service-task --help
aliyun sls --help

並確認已執行 aliyun configure 配置 AccessKey。

建立成功但一直沒有 Capture Results

請依次排查：

1. 讓 Agent 先看 Task Status，確認探針是否安裝成功。

2. 核對 typeName/methodName 是否與運行時模組名、__qualname__ 一致；主模組是否應填 __main__。

3. 確認已觸發會走到目標函數的業務請求；過濾條件是否過嚴。

4. 確認 .arms-info 中的 regionId 與 slsProject 地區一致。

5. 適當加大查詢時間視窗後再查一次。

也可直接對 Agent 說：“一直沒採到資料，幫我看狀態和目標定位是否正確。”

SLS 報 ProjectNotExist

原因： 查詢使用的地區與 SLS Project 所在地區不一致。

解決方案： 開啟 .arms-info，填寫正確的 regionId，並確保 Agent 匯出了 LIVE_DEBUG_REGION_ID，不要只依賴 CLI 預設地區。

如何確認探針已清理乾淨

看一下當前服務還掛著哪些 Live-Debug 探針；如果還有，全部刪掉。

Python 應用能否做線程/記憶體/反編譯診斷？

不能。這些屬於 Command 能力，僅 Java/JVM 支援。Python 請改用日誌、快照、指標或 Span 類訴求。