SLS Query Skill 智能查詢分析日誌 - Simple Log Service

alibabacloud-sls-query 是一個 Agent Skill，支援在 AI Agent 中通過自然語言查詢和分析 SLS 日誌資料。安裝後，Agent 自動將查詢意圖轉換為 SLS 查詢語句並執行，返回結構化分析結果。

適用情境

情境	說明	樣本提示詞
日誌檢索	按關鍵字、欄位、狀態代碼、Trace ID、使用者識別碼等條件查詢日誌明細。	查詢最近 10 分鐘 status>=500 的 NGINX 訪問日誌明細。
SQL 統計分析	對日誌進行彙總、分組、排序、Top-N、趨勢分析或欄位投影。	統計最近 1 小時 5xx 錯誤最多的介面 Top 10。
查詢語句產生	將自然語言需求轉換為 SLS 索引查詢語句、SQL 陳述式或 SPL 語句。	產生按分鐘統計平均延遲和 P95 延後查詢語句。
查詢最佳化	根據索引配置和欄位類型最佳化常設查詢，減少不必要的資料掃描。	最佳化常設查詢語句，優先使用欄位索引並減少不必要的資料掃描。

前提條件

已建立Log Service Project 和 LogStore，並已採集日誌資料。
已為目標 LogStore 建立索引。未配置索引SLS 查詢、SQL 分析和 SPL 查詢無法執行。
已擷取可訪問目標 Project 和 LogStore 的阿里雲帳號憑據。
警告
為防止憑據泄露，不要在 Agent 對話中粘貼 AccessKey ID 或 AccessKey Secret。建議通過環境變數或阿里雲 CLI 設定檔管理認證。

安裝 Skill

alibabacloud-sls-query 已在阿里雲 Skill和ClawHub發布，支援以下安裝方式。

方式一（推薦）：通過 npx 命令安裝

npx 命令隨 Node.js 一起提供。安裝前，執行以下命令確認本地環境可用：

node -v
npx -v

如果終端提示 node 或 npx 不存在，請先前往 Node.js 官網下載並安裝。

執行以下命令安裝 alibabacloud-sls-query Skill：

npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-sls-query

安裝完成後，確認 skills 目錄下存在 alibabacloud-sls-query 目錄，然後重啟 Agent 使 Skill 生效。

方式二：手動下載安裝

從 GitHub Release 下載 alibabacloud-sls-query 安裝包，解壓後將檔案複製到對應 Agent 的 skills 安裝目錄中。

複製完成後，確保 skills 目錄下存在 alibabacloud-sls-query 目錄，然後重啟 Agent 以載入該 Skill。

常見 Agent 的 skills 安裝目錄如下：

Agent	專案級安裝目錄	使用者級安裝目錄
Claude Code	`.claude/skills`	`~/.claude/skills`
Codex	`.agents/skills`	`~/.agents/skills`
Qoder	`.qoder/skills`	`~/.qoder/skills`
QwenCode	`.qwen/skills`	`~/.qwen/skills`
OpenClaw	`.openclaw/skills`	`~/.openclaw/skills`

查詢和分析日誌

安裝完成後，在 Agent 中直接描述 SLS 查詢或分析需求即可觸發該 Skill。Agent 自動執行以下流程：

檢查運行環境（阿里雲 CLI 和 SLS 外掛程式）。
讀取目標 LogStore 的索引配置。
根據需求產生查詢語句（索引查詢、SQL 或 SPL）。
通過阿里雲 CLI 執行查詢。
輸出整理後的結構化結果。

首次執行時，Agent 會引導完成阿里雲 CLI 的安裝和憑據配置。按提示授予執行許可權並完成配置即可。

提示詞最佳實務

提示詞的品質直接影響查詢結果的準確性。編寫提示詞時，建議包含以下資訊：

Project 名稱和 LogStore 名稱。
明確的查詢或分析意圖。例如“分析請求延遲同比變化，按分鐘粒度統計平均延遲”。
查詢時間範圍。例如“最近 15 分鐘”或“2026-04-24 10：00 到 11：00，北京時間”。
期望輸出格式。例如“返回原始日誌"”統計 Top 10""按分鐘畫趨勢“"只返回這些欄位”。

為提高查詢效率和降低成本，建議：

盡量縮小時間範圍，避免全量掃描。
明確指定欄位名（如 status、request_uri），而非模糊描述。
需要 Top-N 結果時，在提示詞中說明具體數量（如 Top 10）。

說明

以下樣本情境中的 Project、LogStore、欄位名和查詢結果均為樣本資料。實際使用時，請替換為實際的資源名稱和日誌欄位。

情境一：查詢最近 15 分鐘的 5xx 錯誤記錄檔

提示詞

查詢 SLS 日誌庫 Project=prod-web，Logstore=nginx-access，最近 15 分鐘 status 大於等於 500 的請求，按時間倒序。

Agent 輸出樣本

查詢模式：索引查詢。
原因：使用者需要按條件返回原始日誌，不涉及彙總、排序分析或欄位投影；status 欄位已配置數實值型別索引，可直接使用範圍查詢。

執行命令：
aliyun sls get-logs-v2 \
  --project prod-web \
  --logstore nginx-access \
  --from 1777016700 \
  --to 1777017600 \
  --query 'status>=500' \
  --line 100 \
  --offset 0 \
  --reverse true

查詢結果：
| 時間 | status | request_uri | upstream_status | request_time | message |
| --- | ---: | --- | ---: | ---: | --- |
| 2026-04-24 15:59:31 | 502 | /api/order/create | 502 | 1.238 | upstream connect timeout |
| 2026-04-24 15:58:44 | 500 | /api/pay/notify | 500 | 0.412 | internal server error |
| 2026-04-24 15:57:09 | 502 | /api/order/create | 502 | 1.104 | bad gateway |

結論：已按時間倒序返回最近 15 分鐘內的 5xx 原始日誌，最新錯誤集中出現在 /api/order/create。

情境二：統計 5xx 錯誤介面 Top 10

提示詞

統計 SLS 日誌庫 prod-web/nginx-access 中最近 1 小時內 5xx 數量 Top 10 的介面。

Agent 輸出樣本

查詢模式：索引查詢 + SQL。
原因：需要統計 5xx 數量 Top10 的介面，因此先用索引查詢過濾 500 到 599 狀態代碼，再用 SQL 按 request_uri 分組、計數並排序。

執行命令：
aliyun sls get-logs-v2 \
  --project prod-web \
  --logstore nginx-access \
  --from 1777014000 \
  --to 1777017600 \
  --query 'status in [500 599] | SELECT request_uri, count(*) AS errors FROM log GROUP BY request_uri ORDER BY errors DESC LIMIT 10'

查詢結果：
| 排名 | request_uri | errors |
| --- | --- | ---: |
| 1 | /api/order/create | 186 |
| 2 | /api/pay/notify | 73 |
.....
| 10 | /api/user/login | 1 |

結論：最近 1 小時內 5xx 數量最高的介面是 /api/order/create，其錯誤量明顯高於其他介面，建議優先排查該介面及其後端依賴。

情境三：對比最近一小時與昨天同期的延遲趨勢

提示詞

分析 SLS 日誌庫 prod-web/nginx-access 中最近一小時與昨天同期相比的平均延遲變化，按分鐘粒度統計平均值，分析延遲是否存在明顯異常。

Agent 輸出樣本

查詢模式：索引查詢 + SQL
原因：需要對當前最近一小時和昨天同期分別按分鐘彙總平均延遲，再按分鐘對齊計算變化量和變動率。

執行命令（當前最近一小時）：
aliyun sls get-logs-v2 \
  --project prod-web \
  --logstore nginx-access \
  --from 1777014000 \
  --to 1777017600 \
  --query "* | SELECT date_trunc('minute', __time__) AS minute, avg(request_time) AS avg_latency FROM log GROUP BY minute ORDER BY minute LIMIT 60"

執行命令（昨天同期）：
aliyun sls get-logs-v2 \
  --project prod-web \
  --logstore nginx-access \
  --from 1776927600 \
  --to 1776931200 \
  --query "* | SELECT date_trunc('minute', __time__) AS minute, avg(request_time) AS avg_latency FROM log GROUP BY minute ORDER BY minute LIMIT 60"

查詢結果：
| 分鐘 | 當前平均延遲 | 昨天同期平均延遲 | 變化量 | 變動率 |
| --- | ---: | ---: | ---: | ---: |
| 2026-04-24 15:00 | 0.132s | 0.118s | +14ms | +11.9% |
| 2026-04-24 15:01 | 0.141s | 0.116s | +25ms | +21.6% |
| 2026-04-24 15:02 | 0.338s | 0.129s | +209ms | +162.0% |
| 2026-04-24 15:03 | 0.351s | 0.131s | +220ms | +167.9% |

結論：最近一小時平均延遲整體高於昨天同期，其中 15:02 到 15:03 上升最明顯，平均延遲增加超過 160%。建議繼續按 request_uri、upstream_addr 或 service 維度下鑽，定位延遲上升來源。

情境四：基於查詢結果繼續追問

SLS Query Skill 支援多輪互動。可以基於前一次查詢結果繼續追問，逐步縮小排查範圍。

第一輪提示詞

統計 SLS 日誌庫 prod-web/nginx-access 中最近 1 小時 5xx 最多的介面 Top 5。

第二輪提示詞（基於第一輪結果追問）

針對 /api/order/create 介面，按分鐘粒度統計錯誤數量趨勢，查看錯誤是集中爆發還是均勻分布。

第三輪提示詞（進一步下鑽）

查看 /api/order/create 在 15：02 到 15：05 之間的 5xx 原始日誌，返回 upstream_addr 和 message 欄位。

通過多輪追問，可以從宏觀統計逐步下鑽到具體時間段的原始日誌，快速定位故障根因。

資料安全與隱私

SLS Query Skill 通過阿里雲 CLI 執行查詢，查詢過程遵循以下安全原則：

查詢請求通過 HTTPS 加密傳輸，日誌資料不經過第三方服務。
Agent 在本地產生和執行查詢命令，日誌資料不會發送給 AI 模型供應商。
憑據資訊（AccessKey）通過阿里雲 CLI 設定檔或環境變數管理，不會出現在 Agent 對話記錄中。

重要

不要在 Agent 對話中直接粘貼 AccessKey ID 或 AccessKey Secret。如需配置憑據，請使用 aliyun configure 命令。

使用限制

限制項	說明
索引配置	目標 LogStore 必須已建立索引。未配置索引時，所有查詢類型均無法執行。
查詢逾時	單次查詢預設逾時時間為 60 秒。逾時後可嘗試縮小時間範圍或簡化查詢條件。
資料掃描量	查詢費用與資料掃描量相關。建議盡量縮小時間範圍和使用欄位索引，減少不必要的全量掃描。
運行環境	需要 Node.js 運行時（用於安裝 Skill）和阿里雲 CLI（用於執行查詢）。

常見問題

是否需要手動安裝阿里雲 CLI 和 SLS 外掛程式？

一般情況下不需要手動安裝。在 Agent 中發起查詢需求後，Agent 會自動檢查環境（aliyun version）、啟用 AI Mode、設定 User-Agent 並執行外掛程式更新。

如果本機未安裝阿里雲 CLI 或版本過低，Agent 會給出安裝或升級指引。按照 Agent 輸出的命令在本機環境中完成安裝即可。

如何配置阿里雲帳號憑據？

可以根據 Agent 引導提示配置帳號憑據，也可以手動執行 aliyun configure 命令配置。支援 AK、StsToken、OAuth、RamRole 等多種憑據配置方式。詳情參考配置憑證。

是否支援內網網域名稱、傳輸加速網域名稱、自訂網域名？

支援。在提示詞中告知 Agent 使用 --endpoint <網域名稱> 指定 Endpoint 即可。

查詢結果不準確怎麼辦？

可以從以下方面排查和最佳化：

確認目標欄位已正確配置索引，且欄位類型與查詢條件匹配（例如 status 應為 long 類型而非 text）。
在提示詞中明確指定欄位名、時間範圍和期望格式，避免模糊描述。
基於 Agent 返回的查詢語句檢查邏輯是否符合預期，通過追問修正查詢條件。

故障排查

報錯 IndexConfigNotExist

該錯誤表示目標 LogStore 沒有索引配置或索引配置為空白。

解決方案：在 SLS 控制台為目標 LogStore 建立索引。建立完成後等待片刻（新資料需要短暫時間才能被索引），然後重新執行查詢。

報錯 Unauthorized

該錯誤表示當前帳號或 RAM 使用者缺少必要許可權。

解決方案：為當前帳號授予以下許可權：

API 名稱	Action	Resource
GetLogsV2	`log:GetLogStoreLogs`	`acs:log:<account>:<region>:project/<Project>/logstore/<Logstore>`
GetIndex	`log:GetIndex`	`acs:log:<account>:<region>:project/<Project>`

報錯 ProjectNotExist

該錯誤通常是 Project 名稱錯誤、地區不正確或訪問了錯誤的 Endpoint。

解決方案：確認以下資訊：

Project 名稱是否準確。
地區是否與 Project 所在地區一致。
網路環境是否需要使用內網 Endpoint。