dsh-grafana-query

English | 繁體中文 | 简体中文 | 日本語

dsh-grafana-query 是一個免費開源、唯讀的 DeepSeek Harness Grafana 插件。 它讓 agent 透過 Grafana 的 datasource proxy 執行 PromQL，並讀取 Grafana unified alerting 的當前狀態，全程不改動 Grafana 的任何資料。

請勿與 npm 上的 dsh-grafana 混淆——那是一個寫入型的 dashboard 編輯器，會把 dashboard JSON 推回 Grafana。本插件做的是相反的事：唯讀的指標查詢與告警狀態。dashboard 與 panel JSON 明確不在範圍內。

Tools

工具	用途
grafana_health	確認實例可連線並回報版本。
grafana_list_datasources	列出 datasource 的 uid、type 與 access 模式。請先呼叫這個。
grafana_query	透過 datasource proxy 執行 instant PromQL 查詢。
grafana_query_range	執行區間 PromQL 查詢，強制套用 step 與點數上限。
grafana_alert_state	讀取 unified alerting 規則的當前狀態。
grafana_list_alert_rules	列出已佈建的告警規則定義。

所有工具皆為唯讀。v0.1 不會在 Grafana 建立、修改、刪除、silence、ack 或暫停任何東西。

硬性上限

以下上限都由插件本身強制，與 Grafana 無關。任何一處被截斷時，meta.truncated 與截斷前的總數都會標示出來。

項目	值
每條 series 的點數（max_points）	預設 200、上限 500。Prometheus 兩端都會回傳，因此 n 秒的區間搭配 step s 會得到 floor(n / s) + 1 個點
區間長度（grafana_query_range）	31 天
單次區間查詢的總點數	20000；超過的 series 會被整條捨棄，不會砍半截
單次查詢的 series 數	maxSeries，預設 100
告警規則筆數（grafana_alert_state、grafana_list_alert_rules）	符合條件的前 500 筆；其餘無法靠翻頁取得，請用篩選參數
每條規則的告警 instance	預設 10、上限 50
每頁筆數	預設 20、上限 100
上游錯誤文字	200 字元，且僅 HTTP 400 才透出

grafana_alert_state 預設只回傳 firing、pending 與 unknown 的規則——inactive 規則預設不會出現， 需要時請用 state 明確指定。

Requirements

• 具備相容 @deepseek-ai/dsh-tools API 的 DeepSeek Harness
• Node.js 22.19 以上（22.x 系列）或 Node.js 24 以上
• Grafana 9.0 以上——只支援 uid 版 datasource proxy（/api/datasources/proxy/uid/:uid/*）， 不支援已 deprecated 的數字 id 路徑

Configuration

export GRAFANA_URL='https://grafana.example.com'
export GRAFANA_TOKEN='glsa_your_service_account_token'

欄位	環境變數	預設	範圍
baseUrl	GRAFANA_URL	必填	http(s) URL，不可內嵌帳密、不可帶 query 或 fragment；可含 sub-path
token	GRAFANA_TOKEN	必填	不可為空
locale	—	en	en、zh-TW、zh-CN、ja
requestTimeoutMs	—	30000	1 – 300000
maxResponseBytes	—	5242880	1 – 52428800
maxSeries	—	100	1 – 1000

plugin 設定的優先權高於環境變數。

Permissions

Grafana service account token（建議）與舊版 API key 都可以用——兩者都走同一個 Authorization: Bearer header。Grafana Cloud 的 Access Policy token（glc_）是給 Cloud 資料端點用的，不適用於這個 API。

實際在 Grafana 上怎麼設

下表的 scope 名稱是 Grafana 內部檢查用的，UI 上並不是這樣勾。建立 service account 時可行的組合是：

1. basic role 選 Viewer——涵蓋 datasources:read 與 datasources:query。
2. 再加 fixed role Alerting → Full read-only access——涵蓋 alert.rules:read 與 alert.provisioning:read。

已於 2026-08-27 在 Grafana Cloud 用這個組合實測，六個工具全部可用。 詳見驗證紀錄。

用最小權限的 token 不會讓工具變難用：Grafana 對 GET /api/datasources 是回傳過濾後的列表， 而不是回 403。因此只被授予單一 datasource Query 權限的 token，grafana_list_datasources 就只會列出那一個——2026-08-27 實測：Viewer token 拿到 26 筆，受限 token 拿到 1 筆。你不會看到一堆 查下去就 403 的項目。（datasource 層級的 Query 權限也隱含允許讀該 datasource 的 metadata， 因此不存在「查得動但讀不到」的狀態。）

Scope 對照

工具	所需權限
grafana_health	無——/api/health 不需認證，因此本工具無法判斷 token 是否有效；要驗證 token 請用 grafana_list_datasources。
grafana_list_datasources	datasources:read
grafana_query、grafana_query_range	datasources:query（另有 datasources:read 才能做前置型別檢查）
grafana_alert_state	alert.rules:read
grafana_list_alert_rules	alert.provisioning:read

Grafana Cloud

baseUrl 指向 stack 本身，並使用在該 stack 建立的 service account token：

export GRAFANA_URL='https://your-stack.grafana.net'
export GRAFANA_TOKEN='glsa_your_service_account_token'

這裡不要用 glc_ 開頭的 Access Policy token。Cloud stack 內建大量 datasource， 請善用 grafana_list_datasources 的 type 與 name_contains 篩選以縮短清單。

Install

bun add dsh-grafana-query

套件內含 cordis.patch.yml，並透過 package.json 的 dsh.bundle.patch 宣告， 讓 DeepSeek Harness registry 能以預設設定載入本插件。

Examples

1. grafana_list_datasources 帶 {"type": "prometheus"} 取得 uid。
2. grafana_query 帶 {"datasource_uid": "prom-1", "query": "up"} 查當前值。
3. grafana_query_range 帶 {"datasource_uid": "prom-1", "query": "rate(node_cpu_seconds_total[5m])", "start": "...", "end": "..."} 查走勢。省略 step 時插件會自動挑一個，讓每條 series 的點數不超過 max_points。
4. grafana_alert_state 不帶參數，看現在有什麼在燒。

Internationalization

把 locale 設為 en、zh-TW、zh-CN 或 ja，可切換模型看到的工具與參數描述。 工具名稱一律維持英文，錯誤訊息也一律是英文。

Security and error behavior

• 每個工具都是唯讀。
• 錯誤永遠不會夾帶 token、Authorization header 或原始 response body。
• 唯一的例外：當 Prometheus 以 HTTP 400 拒絕查詢時，會把結構化的 error 欄位透出， 讓 agent 能修正自己的 PromQL。上限 200 字元，且事前會先跑一次機密過濾。 其他狀態碼一律回傳靜態訊息。
• 回應大小受 maxResponseBytes、maxSeries 以及每條 series 的點數上限三重限制。 任何裁剪都會在 meta.truncated 與裁剪前的總數留下記錄。

Development

bun install
bun run lint
bun run typecheck
bun run test
bun run build

License

MIT