Cloud Monitor：接入 QwenPaw 應用

Container Service ACK 和容器計算服務 ACS 接入

如果您使用自訂鏡像，請先確認鏡像中 QwenPaw 實際啟動並執行 Python 環境與 pip3 所在環境一致。若無法確認鏡像啟動方式、運行使用者或 Python 環境，請使用手動接入探針。

步驟一：探針接入助手（ack-onepilot）安裝

1. 登入Container Service管理主控台，在左側導覽列選擇叢集。

2. 單擊目的地組群名稱，在左側導覽列選擇營運管理 > 組件管理。

3. 在ack-onepilot卡片上單擊安裝。配置相關參數，建議使用預設值，單擊確認。

   說明

   需要保證 ack-onepilot 組件版本大於等於 5.1.1。如果已經安裝較低版本 ack-onepilot，請在組件管理頁面升級 ack-onepilot。

步驟二：修改配置以啟動 AI 應用監控

ACK OnePilot 自動接入不需要先在CloudMonitor 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. 登入CloudMonitor 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. 登入CloudMonitor 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).