技術參考手冊Technical Reference

本章整理 grafana-util 目前常用的指令、共用旗標，以及 profile 解析、輸出格式與 staged / live 的 status 用法。

如果你想逐條對照指令與旗標，請搭配 profile、status、overview 與 access 一起看。

適用對象

• 已經知道自己大概要跑哪個 command，但想確認旗標與輸出格式的人
• 要把 grafana-util 接進腳本、pipeline 或審查流程的人
• 想先了解 profile、secret、輸出格式與 live/staged 差異的人

主要目標

• 先把連線與 secret 規則講清楚
• 再整理常見輸出格式與共用旗標
• 最後讓你在查 help 之前就知道大概該看哪一段

輸出旗標規則

grafana-util 現在把畫面 / 表格 / JSON / YAML 這類格式選擇統一收斂到 --output-format。

標準格式旗標：--output-format

很多 list、review、inspect、dry-run 類指令都用 --output-format。

常見對應關係：

• --output-format table = --table
• --output-format json = --json
• --output-format csv = --csv
• --output-format yaml = --yaml
• --output-format text = --text

如果你是在腳本、CI 或可重複使用的範本裡，通常建議用完整寫法。 如果你是在終端直接操作，短旗標會比較順手。

幾個常見例外

• 不是每個 command 都會把所有短旗標都做齊
• 有些指令只支援一兩種輸出形態
• dashboard topology 是特例：它支援 text、json、mermaid、dot，但沒有 --table 這類快捷旗標
• --output-file，或某些匯出 / draft 指令裡的 --output，代表的是輸出檔案路徑，不是輸出格式

如果你不確定某個 command 到底支援哪些格式，最準的還是該 command 的獨立說明頁。

給 CI 用的 change JSON 文件

change 指令群組會輸出多種 JSON contract。最穩妥的判斷順序是：

1. 先看 kind
2. 再確認 schemaVersion
3. 最後才根據 summary、operations、checks、drifts 等欄位往下判斷

CLI 內建快速查詢：

• grafana-util change --help-schema
• grafana-util change preview --help-schema
• grafana-util change apply --help-schema
• grafana-util change advanced audit --help-schema

常見對應：

• change inspect --output-format json -> 依輸入類型輸出 staged 變更摘要或 overview 風格的 inspection 結果
• change preview --output-format json -> grafana-utils-sync-plan
• change apply --output-format json -> grafana-utils-sync-apply-intent
• change apply --execute-live --output-format json -> live apply result
• change advanced summary --output-format json -> grafana-utils-sync-summary
• change advanced review --output-format json -> grafana-utils-sync-plan
• change advanced audit --output-format json -> grafana-utils-sync-audit
• change advanced preflight --output-format json -> grafana-utils-sync-preflight
• change advanced assess-alerts --output-format json -> grafana-utils-alert-sync-plan
• change advanced bundle-preflight --output-format json -> grafana-utils-sync-bundle-preflight
• change advanced promotion-preflight --output-format json -> grafana-utils-sync-promotion-preflight

對於 grafana-utils-sync-plan，審查者與 CI 也應該直接讀取 preview 文件上的排序欄位：ordering.mode、operations[].orderIndex、operations[].orderGroup、operations[].kindOrder，以及 summary.blocked_reasons。

如果你需要每種文件的 top-level 欄位細節，直接看 change 指令頁 會最快。

給 CI 用的 dashboard history JSON 文件

dashboard history 這組指令也有穩定的 JSON contract 可供自動化流程使用。

如果你要做本機 history 檢視，dashboard history list 也可以直接讀：

• dashboard history export --output ./cpu-main.history.json 產生的單一成品
• dashboard export --include-history --output-dir ./dashboards 產生的 export tree

dashboard history restore 仍然只支援 live。 dashboard history diff 可以比對 live Grafana、可重用 history 成品，或不同日期的 export roots。

判斷順序同樣建議固定成：

1. 先看 kind
2. 再確認 schemaVersion
3. 最後才往下讀巢狀欄位

CLI 內建快速查詢：

• grafana-util dashboard history --help-schema
• grafana-util dashboard history list --help-schema
• grafana-util dashboard history restore --help-schema
• grafana-util dashboard history diff --help-schema
• grafana-util dashboard history export --help-schema

常見對應：

• dashboard history list --output-format json -> grafana-util-dashboard-history-list
• dashboard history list --input-dir ./dashboards --output-format json -> 如果沒有 --dashboard-uid 篩選，會是 grafana-util-dashboard-history-inventory
• dashboard history restore --dry-run --output-format json -> grafana-util-dashboard-history-restore
• dashboard history diff --output-format json -> grafana-util-dashboard-history-diff
• dashboard history export --output ./cpu-main.history.json -> grafana-util-dashboard-history-export

如果你需要每種文件的 top-level 欄位細節，直接看 dashboard history 指令頁 會最快。

共用 diff JSON contract

dashboard diff、dashboard history diff、alert diff、datasource diff 在 --output-format json 模式下共用同一個 JSON envelope。和其他可機器解析的 contract 一樣，最安全的讀法是：

1. 先看 kind
2. 再確認 schemaVersion
3. 最後才讀 summary 與 rows

如果你要查每個指令的 summary 與 row 欄位，請看 共用 diff JSON contract。

CLI schema 快速查詢：

• grafana-util dashboard diff --help-schema
• grafana-util alert diff --help-schema
• grafana-util datasource diff --help-schema

給 CI 用的 status JSON 文件

status staged 與 status live 現在共用同一個明確的 machine-readable contract：

1. 先看 kind
2. 再確認 schemaVersion
3. 最後才讀 overall、domains、topBlockers、nextActions

穩定路由：

• kind -> grafana-util-project-status
• schemaVersion -> 1

CLI schema 快速查詢：

• grafana-util status --help-schema
• grafana-util status staged --help-schema
• grafana-util status live --help-schema

常見對應：

• status staged --output-format json -> grafana-util-project-status
• status live --output-format json -> grafana-util-project-status

Profile、連線與 secret 處理

Profile 是專案本地的設定。grafana-util profile 會讀寫目前工作目錄中的 grafana-util.yaml，--profile 則是從這個檔案裡挑選一個命名 profile。

建議的使用順序

如果你先從實務順序來看，通常會是：先用直接旗標確認連線，再把重複的 URL、帳號和 secret 來源收進 profile，讓日常操作只需要 --profile。

Secret 保存模式：差別與適用情境

grafana-util 不只支援一種 secret 存放方式，因為本機操作、CI 與長期維護的 checkout，需求和風險模型並不一樣。

如果你先從操作順序來想，通常可以這樣排：

1. CI 與自動化：優先用 password_env / token_env
2. macOS 或 Linux 桌面上的日常維運：優先用 os
3. 需要在專案本地加密存放、但不想依賴 OS secret service：用 encrypted-file
4. file 明文模式只留給 demo、一次性 lab、或明確的 bootstrap 情境

macOS 與 Linux 的 OS secret store 支援

os provider 目前是平台後端：

• macOS：透過系統 keyring 整合寫入 Keychain
• Linux：透過系統 keyring 整合寫入 Secret Service

這樣 profile YAML 只會留下像這樣的 reference：

password_store:
  provider: os
  key: grafana-util/profile/prod/password

真正的密碼不會寫進 grafana-util.yaml。

重要限制：

• os 只支援 macOS 與 Linux
• Linux 的 server、container、CI shell 不一定有可用的 Secret Service session
• 如果 OS secret store 不可用，請改用 password_env、token_env 或 encrypted-file

1. 選對 profile 工作流

如果你有設定 GRAFANA_UTIL_CONFIG，設定檔就會跟著那個路徑走。encrypted-file 模式用到的幫助檔也會放在同一個目錄：

如果 encrypted-file 使用這些 repo-local helper 路徑，profile add 也會在尚未忽略時，自動把它們加到 config 目錄的 .gitignore。

2. 初始化、新增並列出 profile

# 用途：2. 初始化、新增並列出 profile。
grafana-util profile init --overwrite

# 用途：2. 初始化、新增並列出 profile。
grafana-util profile add dev --url http://127.0.0.1:3000 --basic-user admin --prompt-password

# 用途：2. 初始化、新增並列出 profile。
grafana-util profile add ci --url https://grafana.example.com --token-env GRAFANA_CI_TOKEN --store-secret os

# 用途：2. 初始化、新增並列出 profile。
grafana-util profile list

# 用途：2. 初始化、新增並列出 profile。
grafana-util profile example --mode full

預期輸出：

Wrote grafana-util.yaml.
dev
prod

init 會建立本機設定檔，add 可以一步直接建立可用 profile，list 會一行列出一個已解析的 profile 名稱，而 example 則會輸出完整註解版範本，方便你拿去改。

3. 顯示已解析的 profile

# 用途：3. 顯示已解析的 profile。
grafana-util profile show --profile prod --output-format yaml

# 用途：3. 顯示已解析的 profile。
grafana-util profile show --profile prod --show-secrets --output-format yaml

預期輸出：

name: prod
source_path: grafana-util.yaml
profile:
  url: https://grafana.example.com
  username: admin
  password_env: GRAFANA_PROD_PASSWORD
  verify_ssl: true

要確認最後解析結果時就用 show。--profile 會覆蓋預設選擇規則，而 yaml 最適合人工檢查連線設定。

--show-secrets 只適合本機除錯或檢查。它會把 secret-store 參照解成明文輸出。

4. 註解版範例輸出

# 沒有指定 --profile 時，預設會用這個 profile。
default_profile: dev

profiles:
  # 本機 demo profile，透過環境變數提供 Basic auth 密碼。
  dev:
    url: http://127.0.0.1:3000
    username: admin
    password_env: GRAFANA_DEV_PASSWORD
    timeout: 30
    verify_ssl: false

  # 從環境變數取得 token。適合權限範圍較窄的自動化。
  ci_token:
    url: https://grafana.example.com
    token_env: GRAFANA_CI_TOKEN
    timeout: 30
    verify_ssl: true

  # 明文範例。好改，但密碼會直接留在 grafana-util.yaml 裡。
  prod_plaintext:
    url: https://grafana.example.com
    username: admin
    password: change-me
    verify_ssl: true

  # OS 密碼保管庫範例。密碼會放進 macOS Keychain 或 Linux Secret Service。
  prod_os_store:
    url: https://grafana.example.com
    username: admin
    password_store:
      provider: os
      key: grafana-util/profile/prod_os_store/password

  # 有 passphrase 的加密秘密檔。secret file 預設會跟 grafana-util.yaml 放同一層。
  prod_encrypted:
    url: https://grafana.example.com
    username: admin
    password_store:
      provider: encrypted-file
      key: grafana-util/profile/prod_encrypted/password
      path: .grafana-util.secrets.yaml

  # 沒有 passphrase 的加密秘密檔。可減少直接看到明文，但不等於能抵擋本機帳號被入侵。
  stage_encrypted_local_key:
    url: https://grafana-stage.example.com
    username: stage-bot
    password_store:
      provider: encrypted-file
      key: grafana-util/profile/stage_encrypted_local_key/password
      path: .grafana-util.secrets.yaml

5. 日常使用時的三種常見驗證範例

# 用途：5. 日常使用時的三種常見驗證範例。
grafana-util status live --profile prod --output-format yaml

# 用途：5. 日常使用時的三種常見驗證範例。
grafana-util status live --url http://localhost:3000 --basic-user admin --prompt-password --output-format yaml

# 用途：5. 日常使用時的三種常見驗證範例。
grafana-util overview live --url http://localhost:3000 --token "$GRAFANA_API_TOKEN" --output-format json

預設請以 --profile 為主。直接 Basic auth 比較適合管理員型流程；token 則適合你已經很清楚權限邊界的 scoped automation。

6. 完整的 secret-handling 範例

# 用環境變數承載密碼，建立可重複使用的本機 profile。
export GRAFANA_PROD_PASSWORD='change-me'
grafana-util profile add prod --url https://grafana.example.com --basic-user admin --password-env GRAFANA_PROD_PASSWORD

# 用環境變數承載密碼，建立可重複使用的本機 profile。
grafana-util status live --profile prod --output-format yaml

# 在 macOS 或 Linux 桌面上，把 secret 放進 OS secret store。
grafana-util profile add prod-os --url https://grafana.example.com --basic-user admin --prompt-password --store-secret os

# 在 macOS 或 Linux 桌面上，把 secret 放進 OS secret store。
grafana-util overview live --profile prod-os --output-format interactive

# 使用帶 passphrase 的加密 secret file。
grafana-util profile add prod-encrypted --url https://grafana.example.com --basic-user admin --prompt-password --store-secret encrypted-file --prompt-secret-passphrase

# 使用帶 passphrase 的加密 secret file。
grafana-util status live --profile prod-encrypted --output-format yaml

# 在自動化流程中，以環境變數承載 scoped token。
export GRAFANA_CI_TOKEN='replace-me'
grafana-util profile add ci --url https://grafana.example.com --token-env GRAFANA_CI_TOKEN

# 在自動化流程中，以環境變數承載 scoped token。
grafana-util overview live --profile ci --output-format json

這組範例的重點是：

• 用同一種 --profile 操作面，對應不同的 secret backend
• 讓日常執行不必每次都重貼密碼
• 把 env、OS secret store、encrypted-file 與 token 模式都完整交代

7. 多 org 與管理員範圍的注意事項

• --all-orgs 最適合搭配管理員憑證支援的 --profile 或直接 Basic auth。
• Token 只能看到它被授權看到的範圍。多 org inventory、org export/import、user 或 team 管理，都可能因 token 權限不足而只回傳部分資料或直接失敗。
• access org、access user、access team 與 service account 建立、輪替、清理這類操作，通常需要比窄權限 API token 更高的 Grafana 權限。

8. Secret storage 常見排解

先確認 security 工具有沒有正常可用，以及目前登入 session 能不能存取 Keychain。

很可能目前環境沒有可用的 Secret Service session；這在 headless shell、container、精簡 server 上很常見。請改用 password_env、token_env 或 encrypted-file。

請確認對應的 env var 仍存在、OS secret store 裡的 key 仍存在，或加密 secret file 與 passphrase/local key 還在。

目標 checkout 必須同時有 .grafana-util.secrets.yaml，以及相同的 passphrase 或對應的 local key file。

代表 credential 本身有效，但權限範圍不夠。請改用管理員等級的 Basic auth 或 admin-backed profile。

• profile add --store-secret os 在 macOS 失敗：
• profile add --store-secret os 在 Linux 失敗：
• profile show --show-secrets 無法解出 secret：
• encrypted-file 在一台機器可用、另一台不行：
• profile 在一般 live 指令可用，但 --all-orgs 或存取管理相關指令失敗：

輸出格式對照

grafana-util 同時提供各格式旗標與單一 --output-format 選擇器。以 dashboard list 來說，目前可用的是 --json、--table、--csv、--yaml 與 --output-format。

0. 先看這張旗標對照表

1. 表格或 JSON 的選擇

# 用途：1. 表格或 JSON 的選擇。
grafana-util dashboard list -h

預期輸出：

--text
--table
--csv
--json
--yaml
--output-format <OUTPUT_FORMAT>

--json 適合自動化，--table 適合快速人工檢查，而 --output-format 則適合想用單一旗標切換輸出格式的情境。舊版文件中的 --limit 範例已不符合現況，現在應該用 --page-size 控制抓取大小、用 --output-columns 控制欄位。

2. Live status 與 overview 的輸出選擇器

# 用途：2. Live status 與 overview 的輸出選擇器。
grafana-util status live -h

# 用途：2. Live status 與 overview 的輸出選擇器。
grafana-util overview live -h

預期輸出：

Render project status from live Grafana read surfaces. Use current Grafana state plus optional staged context files.
...
--output-format <OUTPUT_FORMAT>
    Render project status as table, csv, text, json, yaml, or interactive output.

Render a live overview by delegating to the shared status live path.
...
--output-format <OUTPUT_FORMAT>
    Render project status as table, csv, text, json, yaml, or interactive output.

這兩個 live 入口現在都用 --output-format。

Dashboard 路徑

• raw/ 是給 API replay/import 使用的路徑。
• prompt/ 是給 Grafana UI 匯入使用的路徑。
• dashboard export 會直接產生 prompt 路徑。
• dashboard raw-to-prompt 可以把一般或 raw 的 dashboard JSON 轉成 prompt JSON，方便修補或遷移成 Grafana UI 匯入格式。
• dashboard import 只吃 raw/ 或 provisioning/ 輸入，不吃 prompt/。

自動化與腳本開發 (CI/CD)

1. 使用 jq 進行過濾 (Bash/Zsh)

# 取得 org ID 為 5 的所有 Dashboard UID
grafana-util dashboard list --profile prod --json | jq -r '.[] | select(.orgId == 5) | .uid'

這是目前可用的 JSON 腳本路徑。如果需要更少或不同欄位，請改用 --output-columns，不要再假設舊版表格欄位還存在。

2. 處理結束代碼 (Exit Codes)

# 用途：2. 處理結束代碼 (Exit Codes)。
grafana-util status live --profile prod --output-format json
if [ $? -eq 2 ]; then
  echo "CRITICAL: Grafana 連線受阻！"
  exit 1
fi

⬅️ 上一章：維運實戰場景 | 🏠 回首頁 | ➡️ 下一章：實戰錦囊與最佳實踐