通过 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 类诉求。