云监控：接入 QwenPaw 应用

容器服务 ACK 和容器计算服务 ACS 接入

如果您使用自定义镜像，请先确认镜像中 QwenPaw 实际运行的 Python 环境与 pip3 所在环境一致。若无法确认镜像启动方式、运行用户或 Python 环境，请使用手动接入探针。

步骤一：探针接入助手（ack-onepilot）安装

1. 登录容器服务管理控制台，在左侧导航栏选择集群。

2. 单击目标集群名称，在左侧导航栏选择运维管理 > 组件管理。

3. 在ack-onepilot卡片上单击安装。配置相关参数，建议使用默认值，单击确认。

   说明

   需要保证 ack-onepilot 组件版本大于等于 5.1.1。如果已经安装较低版本 ack-onepilot，请在组件管理页面升级 ack-onepilot。

步骤二：修改配置以启动 AI 应用监控

ACK OnePilot 自动接入不需要先在云监控 2.0 控制台获取接入命令。请在 Deployment 的 spec.template.metadata.labels 中添加以下标签，并将应用名和工作空间替换为实际值：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: qwenpaw
spec:
  template:
    metadata:
      labels:
        aliyun.com/app-language: python
        armsPilotAutoEnable: "on"
        armsPilotCreateAppName: "qwenpaw-demo"
        armsPilotAppWorkspace: "<Your-Workspace>"
    spec:
      containers:
        - name: qwenpaw
          image: agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw:latest

更新工作负载后，等待 Pod 重新创建并启动。启动日志中出现 Aliyun python agent is started，表示 Python 探针已经随应用进程加载。

手动接入探针

适用于不使用 ack-onepilot、自定义镜像无法确认注入条件或希望将探针安装过程纳入镜像构建流程的场景。请在镜像构建阶段或容器启动前，使用 QwenPaw 所在 Python 环境执行控制台生成的安装命令。

步骤一：获取接入参数

1. 登录云监控 2.0 控制台，选择目标工作空间。

2. 在左侧导航栏单击接入中心。

3. 在AI 应用可观测区域选择 QwenPaw 接入项。

4. 在参数配置区域输入应用名，根据部署环境选择连接方式，然后单击LicenseKey右侧的点击获取。

5. 记录页面生成的 Endpoint、LicenseKey、Project、Workspace 和 serviceName 等接入参数。

步骤二：构建内置探针的 QwenPaw 镜像

FROM agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw:latest

RUN curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/qwenpaw-cms-plugin/install.sh | bash -s -- \
  --python /app/venv/bin/python \
  --skip-qwenpaw-check \
  --site-bootstrap \
  --x-arms-license-key "<Your-LicenseKey>" \
  --x-arms-project "<Your-Project>" \
  --x-cms-workspace "<Your-Workspace>" \
  --serviceName "qwenpaw-demo" \
  --endpoint "https://<Endpoint>/apm/trace/opentelemetry"

如果在容器启动阶段执行安装命令，请确保安装完成后再启动 qwenpaw app，并重新创建 Pod 使环境变量和站点初始化配置生效。

个人 PC 接入

适用于本地 macOS、Linux、Windows WSL 或个人开发机上的开发调试、PoC 验证、问题复现或短期验证。该方式通过 site bootstrap 方式让本地 Python 进程启动时加载可观测能力，安装步骤较轻量；如果 QwenPaw 部署在 ACK、ACS、容器镜像中，或需要长期运行，请优先使用手动接入探针。

步骤一：获取接入命令

1. 登录云监控 2.0 控制台，选择目标工作空间。

2. 在左侧导航栏单击接入中心。

3. 在AI 应用可观测区域选择 QwenPaw 接入项。

4. 在参数配置区域输入应用名，选择个人 PC 接入方式后复制页面生成的安装命令。命令中包含 Endpoint、LicenseKey、Project、Workspace 和 serviceName 等信息。

步骤二：安装可观测插件

在 QwenPaw 所在机器上执行安装命令。如果 QwenPaw 运行在 conda 环境中，请先执行 conda activate qwenpaw 切换环境。

curl -fsSL https://arms-apm-cn-hangzhou-pre.oss-cn-hangzhou.aliyuncs.com/qwenpaw-cms-plugin/install.sh | bash -s -- \
  --x-arms-license-key "<Your-LicenseKey>" \
  --x-arms-project "<Your-Project>" \
  --x-cms-workspace "<Your-Workspace>" \
  --serviceName "qwenpaw-demo" \
  --endpoint "https://<Endpoint>/apm/trace/opentelemetry"

安装成功后，终端会输出类似如下内容：

qwenpaw-cms-plugin installed successfully!

步骤三：启动 QwenPaw 应用

插件安装完成后，先设置环境变量，再启动 QwenPaw：

export LOONGSUITE_PYTHON_SITE_BOOTSTRAP=true
qwenpaw app

如果应用已经在运行，请先停止后重新启动。启动后访问 http://127.0.0.1:8088/ 打开 QwenPaw Console，并发起一次对话或任务。

如果终端出现以下提示，表示 OpenTelemetry 自动埋点已经初始化：

loongsuite-site-bootstrap: started successfully (OpenTelemetry auto-instrumentation initialized).