grafana-oss

Grafana OSS

文件：https://grafana.com/docs/grafana/latest.md

常見工作流程

從磁碟佈建儀表板

1. 將儀表板 JSON 檔案放置於 /var/lib/grafana/dashboards/ 目錄下
2. 在 provisioning/dashboards/default.yaml 中新增提供者（請參閱下方 § 儀表板佈建）
3. 重新啟動 Grafana 以載入提供者設定
4. 驗證儀表板是否已成功載入：

   curl https://grafana.example.com/api/dashboards/uid/<uid> \
     -H "Authorization: Bearer <token>" | jq '.dashboard.title'
   

   回傳標題表示成功。若回傳 404，表示佈建未偵測到該檔案；請檢查 Grafana 伺服器記錄檔（journalctl -u grafana-server | grep -i provisioning）以找出解析錯誤。

佈建資料來源

1. 撰寫 provisioning/datasources/datasources.yaml（請參閱下方 § 資料來源佈建）
2. 重新啟動 Grafana
3. 透過 API 健康檢查資料來源：

   curl https://grafana.example.com/api/datasources/uid/<uid>/health \
     -H "Authorization: Bearer <token>"
   # { "status": "OK", "message": "..." } → 正常運作
   # { "status": "ERROR", ... } → URL 無法連線或驗證設定錯誤
   

建立服務帳戶與權杖

1. 透過 YAML 或 POST /api/serviceaccounts 進行佈建（完整 API 請參閱 references/api.md § 使用者 + 服務帳戶）
2. 透過 POST /api/serviceaccounts/{id}/tokens 產生權杖
3. 驗證權杖是否有效：

   curl https://grafana.example.com/api/org \
     -H "Authorization: Bearer <new-token>"
   # 200 + org JSON → 權杖與角色指派正常
   # 401 → 權杖錯誤；403 → 角色錯誤
   

儀表板佈建

# provisioning/dashboards/default.yaml
apiVersion: 1
providers:
  - name: default
    folder: MyFolder
    type: file
    disableDeletion: false
    updateIntervalSeconds: 30
    options:
      path: /var/lib/grafana/dashboards
      foldersFromFilesStructure: true

關於儀表板 JSON 本身的結構（面板、查詢、範本變數），請參閱 references/dashboard-json.md。

資料來源佈建

# provisioning/datasources/datasources.yaml
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    jsonData:
      timeInterval: 15s
      httpMethod: POST

  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100

  - name: Tempo
    type: tempo
    access: proxy
    url: http://tempo:3200
    jsonData:
      tracesToLogsV2:
        datasourceUid: loki_uid
        tags: [{ key: "service.name", value: "app" }]
      serviceMap:
        datasourceUid: prometheus_uid
      nodeGraph:
        enabled: true

  - name: Pyroscope
    type: grafana-pyroscope-datasource
    url: http://pyroscope:4040

RBAC（內建角色）

角色	權限
Viewer	讀取儀表板、警示
Editor	建立/編輯儀表板、警示
Admin	管理資料來源、使用者、外掛
GrafanaAdmin	全伺服器管理員（超級使用者）

服務帳戶佈建：

# provisioning/access-control/service_accounts.yaml
apiVersion: 1
serviceAccounts:
  - name: ci-reader
    orgId: 1
    role: Viewer
    tokens:
      - name: ci-token
        # expires: 可選的 ISO 8601 時間戳；省略則為無到期權杖

（具有細粒度權限的自訂 RBAC 角色僅限 Enterprise / Cloud 版本 — 如需此功能，請參閱 grafana-cloud/admin 技能。）

外掛佈建

# provisioning/plugins/plugins.yaml
apiVersion: 1
apps:
  - type: grafana-pyroscope-app
    disabled: false
    jsonData:
      backendUrl: http://pyroscope:4040

重新啟動後，可透過 GET /api/plugins/<plugin-id>/health 驗證。

參考資料

• references/dashboard-json.md — 完整的儀表板 JSON 模型 + 範本變數 + 常見問題（uid 唯一性、gridPos 運算、資料來源 uid 比對）
• references/dashboards.md — 儀表板工作流程、設定、變數、註解、分享、版本、播放清單以及基礎架構即程式碼的佈建
• references/datasources.md — 資料來源設定與 Prometheus、Loki、Tempo、SQL、CloudWatch 及外掛的查詢範例
• references/panel-types.md — 面板類型表格 + 選擇正確面板類型的決策指南
• references/panels.md — 面板編輯器、視覺化選項、欄位設定、轉換、查詢選項、檢查與效能提示
• references/alerting.md — 警示概念、聯絡點、通知政策、範本、靜音與常見規則範例
• references/api.md — 完整的 Grafana OSS API 參考（儀表板、資料來源、使用者、服務帳戶、註解），附帶驗證 curl 與常見失敗模式
• references/config.md — grafana.ini 伺服器/資料庫/SMTP/驗證/安全性/功能切換設定 + 需重新啟動的注意事項