通過API批量啟用Dify LLM應用監控 - CloudMonitor

Dify 控制台上可以為各個應用配置監控並接入CloudMonitor可觀測，但缺乏大量設定監控的能力。本文介紹如何通過調用介面自動化大量設定 Dify 應用的阿里雲可觀測監控。

背景

整體方案流程是通過類比 Dify 控制台操作，使用 HTTP API 實現大量設定：

擷取登入態：調用登入介面擷取認證 Token。
擷取應用列表：擷取租戶下所有應用資訊。
檢查應用監控配置：查詢應用當前的監控配置狀態。
配置阿里雲監控：為應用建立阿里雲可觀測配置。
啟用監控開關：開啟應用監控。

若從 Dify 源碼部署並做二次開發，也可參考上述流程和 Dify ext_commands.py 中的現有營運命令，用 Click Command 實現大量設定。

API 大量設定流程

步驟一：登入認證

調用 Dify 登入介面進行身份認證，擷取租戶的登入態 Token 資訊。

介面：POST {base_url}/console/api/login

請求參數

{
  "email": "your_account@example.com",
  "password": "your_password",
  "remember_me": false
}

響應

{
  "result": "success"
}

Set-Cookie: access_token=<JWT>; HttpOnly; Max-Age=3600
Set-Cookie: refresh_token=<random>; HttpOnly; Max-Age=2592000
Set-Cookie: csrf_token=<JWT>; Max-Age=3600

響應中的關鍵資訊

Cookie	用途
`access_token`	API 認證憑證
`refresh_token`	access_token 續期憑證
`csrf_token`	CSRF 憑證

後續請求

在請求 Header 中設定：

Cookie: access_token=xxx; refresh_token=xxx; csrf_token=xxx
X-CSRF-Token: <csrf_token>

說明

如果使用帶 Session 功能的庫，通常會自動管理 Cookie，此時在 Header 中添加 X-CSRF-Token 即可。

步驟二：擷取應用列表

擷取當前租戶下的所有應用資訊。

介面：GET {base_url}/console/api/apps

請求參數

參數	類型	預設值	說明
`page`	int	1	頁碼（從 1 開始）
`limit`	int	20	每頁數量（1-100）
`mode`	string	"all"	應用類型過濾
`name`	string	-	應用程式名稱搜尋

分頁說明:

通過返回的 has_more 欄位判斷是否有下一頁。
擷取所有應用需迴圈請求，直到響應中的 has_more 為 false。

響應

{
  "page": 1,
  "limit": 20,
  "total": 100,
  "has_more": true,
  "data": [
    {
      "id": "app-uuid",
      "name": "應用程式名稱",
      "mode": "workflow",
      "description": "應用描述",
      "icon": "",
      "icon_type": "emoji",
      "created_at": 1234567890,
      "updated_at": 1234567890,
      "model_config": { /* 模型配置 */ },
      "workflow": { /* workflow 配置 */ },
      "tags": []
    }
  ]
}

關鍵字段說明:

id: 應用標識（後續配置監控步驟需要）。
name: 應用程式名稱（後續配置監控的 app_name 需要）。

步驟三：檢查應用監控配置

擷取指定應用當前的監控配置狀態，未配置監控才進行後續步驟。

介面：GET {base_url}/console/api/apps/{app_id}/trace

請求參數

app_id: 應用 ID（從步驟二：擷取應用列表擷取）。

響應

{
  "enabled": false,
  "tracing_provider": null
}

{
  "enabled": true,
  "tracing_provider": "aliyun"
}

欄位說明:

enabled: 是否已啟用監控（boolean）。
tracing_provider: 監控供應商名稱（string）。

步驟四：配置阿里雲監控

為應用建立阿里雲可觀測監控配置。

介面：POST {base_url}/console/api/apps/{app_id}/trace-config

請求參數

{
  "tracing_provider": "aliyun",
  "tracing_config": {
    "app_name": "xxx",
    "license_key": "your_aliyun_license_key",
    "endpoint": "http://tracing-analysis-dc-bj.aliyuncs.com"
  }
}

欄位說明

欄位	說明
`tracing_provider`	固定為 `"aliyun"`
`tracing_config.app_name`	阿里雲應用程式名稱。大量設定時不能填相同名稱，相同名稱會被視為同一個可觀測應用。可以使用 `Dify工作空間名稱`-`Dify應用程式名稱`命名
`tracing_config.license_key`	阿里雲 License Key，可通過DescribeTraceLicenseKey - 列出LicenseKey擷取。
`tracing_config.endpoint`	阿里雲上報端點，參考服務存取點。

響應

{
  "result": "success"
}

說明

Dify 的某些版本裡如果執行了建立應用配置，但未開啟配置開關，控制台監控項顯示會異常，啟用監控開關後會恢複。

步驟五：啟用監控開關

配置完成後需要啟用監控開關才會生效。

介面：POST {base_url}/console/api/apps/{app_id}/trace

請求參數

{
  "enabled": true,
  "tracing_provider": "aliyun"
}

欄位	類型	說明
`enabled`	boolean	是否啟用監控（true/false）
`tracing_provider`	string	監控供應商名稱（aliyun）

響應

{
  "result": "success"
}