Grafana 使用文档

Grafana 使用文档

适用版本：Grafana 13.x （当前最新 13.2.0；12.x 引入 Observability as Code、Drilldown 下钻体验、Git 同步等重大变化，文档均覆盖）。

本文覆盖：安装部署、数据源、仪表盘与面板、变量模板、统一告警、权限、API/Provisioning、Explore 关联、插件生态与最佳实践。

---

目录

1. [Grafana 概述](#Grafana 概述)
2. 安装与部署
3. [数据源（Data Sources）](#数据源（Data Sources）)
4. 仪表盘与面板（重点）
5. 变量与模板（重点）
6. 统一告警（重点）
7. 用户与权限管理
8. [Dashboard as Code 与 HTTP API](#Dashboard as Code 与 HTTP API)
9. [Explore 与日志/链路关联](#Explore 与日志/链路关联)
10. 插件生态
11. 性能优化与最佳实践
12. 常见问题排查（FAQ）

---

1. Grafana 概述

1.1 是什么

Grafana 是开源的可观测性平台 ：把分散在 Prometheus、Loki、Tempo、MySQL、Elasticsearch、CloudWatch 等各种后端中的数据，统一以仪表盘、告警和探索界面的形式呈现。它自己不存数据，而是通过插件化的数据源连接各种后端。

三大核心能力：

• 可视化（Dashboards）：时间序列、日志、链路、表格、热力图等几十种面板，支持变量模板；
• 告警（Unified Alerting）：跨数据源的统一告警规则、通知策略与静默；
• 探索（Explore）：交互式查询、日志与指标/链路互相跳转关联。

1.2 版本形态

形态	说明
Grafana OSS	开源免费，本文主线
Grafana Enterprise	商业增强（企业数据源、审计、高级权限、支持）
Grafana Cloud	官方托管（免费额度 + 按量付费，含托管的 Prometheus/Loki/Tempo）

1.3 核心概念速览

概念	说明
Data Source	数据源连接（地址 + 认证 + 方言）
Dashboard	仪表盘，由若干 Panel 组成，归属于 Folder
Panel	面板 = 一个查询 + 一种可视化 + 样式配置
Folder	文件夹，组织仪表盘并承载权限
Variable	变量，让仪表盘可筛选、可模板化
Annotation	注解，在图上标记事件（发布、告警等）
Organization / Team	组织/团队，权限隔离单位
Provisioning	用文件声明式管理数据源/仪表盘/告警等

1.4 近年重要变化（升级必读）

• 8.0：统一告警（Unified Alerting）取代旧 Dashboard Alert；
• 10.x：全新 UI、Panel 编辑重构、公共仪表盘（Public Dashboards）；
• 12.x：Observability as Code（Git 同步仪表盘/告警）、Drilldown 应用（指标/日志/链路下钻）、原生录制规则管理；
• 13.x ：Drilldown 与 AI 辅助能力持续增强；Scripted Dashboards 将在 14 中移除，请改用 Dashboard as Code。

---

2. 安装与部署

2.1 二进制部署（Linux）

# Debian/Ubuntu
sudo apt-get install -y apt-transport-https software-properties-common wget
sudo mkdir -p /etc/apt/keyrings/
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update && sudo apt-get install grafana

sudo systemctl enable --now grafana-server

其他发行版/平台见官方下载页（含 rpm、tar.gz、Windows、macOS）。

2.2 Docker 部署

docker run -d --name grafana \
  -p 3000:3000 \
  -v grafana-data:/var/lib/grafana \
  grafana/grafana-oss:13.2.0

2.3 Docker Compose（Prometheus + Grafana 一站式）

services:
  prometheus:
    image: prom/prometheus:v3.14.0
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --web.enable-lifecycle
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prom-data:/prometheus
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana-oss:13.2.0
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin123     # 生产务必改掉
      - GF_USERS_ALLOW_SIGN_UP=false           # 关闭自助注册
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning   # 声明式配置
    ports:
      - "3000:3000"
    depends_on:
      - prometheus

volumes:
  prom-data:
  grafana-data:

2.4 关键配置（grafana.ini / 环境变量）

配置文件默认路径：/etc/grafana/grafana.ini。所有配置项都可用环境变量覆盖，规则：GF_<SECTION>_<KEY>，如 [security] admin_password → GF_SECURITY_ADMIN_PASSWORD。

[server]
http_port = 3000
domain = grafana.example.com          # 对外域名
root_url = https://grafana.example.com/   # 反代/外部访问地址（子路径部署必配）
serve_from_sub_path = false           # true 表示部署在子路径下

[security]
admin_password = 改成强密码
secret_key = 生成一个随机长字符串      # 加密数据源密码等敏感信息
cookie_secure = true                  # 启用 HTTPS 后置 true

[users]
allow_sign_up = false                 # 生产关闭自助注册

[smtp]                                # 邮件告警通道
enabled = true
host = smtp.example.com:465
user = alert@example.com
password = 密码或引用 $__env{SMTP_PASS}
from_address = alert@example.com
startTLS_policy = MandatoryStartTLS

[auth.anonymous]                      # 匿名访问（谨慎）
enabled = false

[database]                            # 默认 sqlite3；HA 部署用 mysql/postgres
;type = mysql
;host = mysql:3306
;name = grafana
;user = grafana
;password =

HA 注意：Grafana Server 本身无状态程度高，可多副本 + LB；但告警评估需要单活（多副本时通过数据库锁选主），数据库必须用 MySQL/Postgres 而非 sqlite。

2.5 首次登录

访问 http://<host>:3000，默认账号 admin / admin（首次登录强制改密）。左侧菜单核心入口：Dashboards、Explore、Alerting、Connections（数据源）、Administration。

3. 数据源（Data Sources）

3.1 常用数据源一览

数据源	用途	查询语言
Prometheus / Mimir / VictoriaMetrics	指标	PromQL
Loki	日志	LogQL
Tempo / Jaeger / Zipkin	链路	TraceQL / TraceID
MySQL / PostgreSQL	业务库指标/时序表	SQL
InfluxDB	时序	InfluxQL / Flux
Elasticsearch / OpenSearch	日志/文档	Lucene / PPL
CloudWatch / Azure Monitor / Stackdriver	云厂商指标	原生查询
Infinity	通用 JSON/CSV/GraphQL API	JSONPath 等
TestData	测试/演示	内置模拟数据

3.2 添加数据源（UI）

Connections → Data sources → Add data source → 选择类型 → 填写：

• Connection ：URL（容器网络中用服务名，如 http://prometheus:9090）；
• Auth：Basic auth / TLS 证书 / Token；
• 点击 Save & test 验证连通。

3.3 Prometheus 数据源关键设置

设置项	说明
Prometheus URL	http://prometheus:9090
Prometheus type	选 Prometheus / Mimir / Thanos（影响分页与元数据能力）
Scrape interval	与后端抓取间隔一致（影响 $__interval 下限）
Custom query parameters	如 Thanos 的 dedup 去重
Exemplars	开启后 Time series 面板显示示例点，可跳转到 Tempo 链路
Disable metrics lookup	关闭指标名自动补全（超大环境提速）

3.4 Provisioning：数据源即代码（推荐生产使用）

/etc/grafana/provisioning/datasources/datasources.yml：

apiVersion: 1

datasources:
  - name: Prometheus
    uid: prometheus              # 固定 uid，方便仪表盘引用
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true
    jsonData:
      timeInterval: 15s          # 抓取间隔
      httpMethod: POST
    editable: false              # UI 中锁定，防止被手改

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

  - name: MySQL-Orders
    type: mysql
    url: mysql:3306
    database: orders
    user: grafana_reader
    secureJsonData:              # 敏感信息单独字段
      password: ${MYSQL_PASS}    # 可引用环境变量

修改后重启容器或调用 POST /api/admin/provisioning/datasources/reload 生效。

3.5 Mixed 数据源与 Correlations

• 一个面板里每条查询可选不同数据源（数据源选 Mixed），适合「业务指标 + 基础设施指标」叠加对照；
• Correlations ：在数据源配置中定义跳转关系（如 MySQL 的 trace_id 字段 → Tempo 的 TraceID 查询），实现日志/数据库记录一键跳链路。

---

4. 仪表盘与面板（重点）

4.1 创建流程

Dashboards → New dashboard → Add visualization → 选数据源 → 写查询 → 选可视化类型 → 配置样式 → Save（必须选 Folder 并命名）。

4.2 常用面板类型详解

面板	适用	要点
Time series	时序曲线（默认首选）	支持多序列、阈值线、Exemplars；Legend 用 {``{instance}} 模板
Stat	单个关键数字（当前 QPS、错误率）	可设 Color mode/Graph mode（迷你趋势线）
Gauge	百分比/水位（磁盘使用率）	配 Thresholds 红黄绿分段
Bar gauge	多实例水位对比	横向条形，按阈值着色
Table	明细数据	用 Transformations 整理列；支持单元格着色
Logs	Loki 日志	支持高亮、换行、Derived fields 跳转
Heatmap	分布变化（延迟分布）	直接查 Histogram 的 bucket 序列
Histogram	某时刻的分布	与 Heatmap 互补
State timeline	状态随时间变化（up/down、发布状态）	值映射成文字与颜色
Status history	多对象状态矩阵	类似状态时间线的表格化视图
Candlestick	股票/金融 K 线	需要 open/high/low/close 字段
Traces	链路瀑布图	数据源为 Tempo 等
Node graph	拓扑图（服务依赖）	需要 nodes/edges 两组数据
Canvas	自由绘制（机房示意图等）	拖拽元素 + 数据绑定
Text	说明文字	支持 Markdown，写 Runbook 链接

面板编辑页右上角有 Visualization suggestions，可依据查询结果自动推荐面板类型。

4.3 查询编辑器要点（以 Prometheus 为例）

• Builder / Code 双模式：Builder 图形化拼 PromQL，Code 手写，可互相转换；
• Legend 字段 ：{``{instance}} - {``{handler}} 自定义图例；
• Format：Time series（曲线）/ Table（表格）/ Heatmap；
• Min step ：最小步长，通常留空让 $__interval 自适应；
• Type：Range（区间，默认）/ Instant（即时，常用于 Stat/Table 取当前值）/ Both；
• Query 标签 ：用 A / B / C 区分多条查询，告警条件中会引用。

4.4 Transformations（数据后处理）

面板级数据加工管道，常用：

Transformation	作用
Organize fields	改名、排序、隐藏列
Merge	合并多个查询结果
Reduce	序列 → 单值（max/mean/last）
Calculate field	新增计算列（如 B/A 错误率）
Filter data by values	按条件过滤行
Group by	分组聚合
Join by field	按字段连接（类似 SQL join）
Sort by / Limit	排序 / 截断

复杂表格类面板（Table）几乎都靠 Transformations 拼装出来。

4.5 面板通用样式设置

• Unit：单位必须正确（bytes、percent(0-100)、reqps、s/ms...），Grafana 会自动换算；
• Thresholds：阈值分档 + 着色（Gauge/Stat/Table 单元格）；
• Value options：显示 last/mean/max、小数位数；
• Standard options → Color scheme：单色 / 按阈值 / 连续色带；
• Overrides ：对某条序列单独设置（如把 error 序列画成红色粗线）；
• Panel options → Data links：给面板/序列加跳转链接（跳到其他仪表盘或 Explore）。

4.6 Annotations（注解）

Dashboard settings → Annotations，例：

# 显示本仪表盘上触发的告警
数据源：-- Grafana --
类型：Annotations & alerts

# 从 Prometheus 标记发布事件
expr: changes(process_start_time_seconds{job="app"}[1m]) > 0
step: 1m

效果：时间轴上出现竖线标记，悬停显示详情，排障时对照「指标恶化」与「事件发生」非常有用。

4.7 Dashboard 设置项（Dashboard settings）

• Variables：见第 5 章；
• Annotations：见上；
• General：自动刷新间隔、时间范围、标签（便于搜索）；
• Panel options：面板拖拽/编辑权限；
• JSON Model：仪表盘的完整 JSON 定义（备份/迁移用）；
• Library panels：可复用面板，多处引用同一块配置。

---

5. 变量与模板（重点）

变量让一个仪表盘覆盖所有实例/环境，顶部出现下拉筛选框。定义入口：Dashboard settings → Variables → New variable。

5.1 变量类型

类型	用途	示例
Query	从数据源动态取候选值（最常用）	label_values(node_cpu_seconds_total, instance)
Custom	手写固定候选值（逗号分隔）	prod, staging, dev
Constant	固定单值（常用于环境标识）	prod
Data source	选择数据源本身	面板数据源引用 ${ds}
Interval	时间间隔下拉	1m, 5m, 15m, 1h
Ad hoc filters	对某数据源全局追加标签过滤（仅部分数据源支持）	instance = 10.0.0.1
Text box	自由输入文本	关键字搜索

5.2 Query 变量配置要点

Name:     instance
Type:     Query
Data source: Prometheus
Query:    label_values(node_cpu_seconds_total, instance)
Refresh:  On dashboard load / On time range change
Sort:     Alphabetical (asc)
Multi-value: ✔    Include All option: ✔   (Custom all value 可选，如 .* )

常用取值函数（Prometheus）：

label_values(<metric>, <label>)                    # 某指标某标签的所有值
label_values(<metric>{k="v"}, <label>)             # 带过滤
metrics(<regex>)                                   # 按正则列指标名

链式变量 ：region 变量选完后再定义 instance 变量，查询中引用 $region，实现逐级筛选：

label_values(node_cpu_seconds_total{dc="$dc"}, instance)

5.3 在查询中使用变量

# 单值
sum(rate(http_requests_total{instance="$instance"}[$__rate_interval]))

# 多值：Grafana 自动展开为正则 {instance=~"$instance"}
sum by (instance) (rate(http_requests_total{instance=~"$instance"}[$__rate_interval]))

# All 选项（默认展开为 .*，可在 Custom all value 中覆盖）

多值变量在 PromQL 里要用 =~ 正则匹配；标签值含 . 等特殊字符时，可用 ${instance:regex} 自动转义。

5.4 内置全局变量

变量	含义
$__interval / ${__interval_ms}	按时间范围自动计算的理想步长（面板数×分辨率），做 rate/avg_over_time 的区间首选
$__rate_interval	$__interval 与 4×scrape interval 取大者，Prometheus rate 查询强烈推荐
$__timeFrom() / $__timeTo()	当前时间范围（SQL 数据源过滤必备）
$__timeFilter(time_col)	SQL：生成时间列的范围条件
$__unixEpochFilter(time_col)	SQL：Unix 时间戳过滤
$__dashboard / $__org	当前仪表盘/组织信息

SQL 数据源示例（MySQL）：

SELECT
  $__timeGroupAlias(created_at, $__interval) AS time,
  count(*) AS orders
FROM orders
WHERE $__timeFilter(created_at) AND channel = '$channel'
GROUP BY 1

5.5 变量的其他能力

• 变量出现在 URL 中 ：?var-instance=xxx，可直接分享带筛选状态的链接；
• Repeated panels / rows：按多值变量自动复制面板或行（每个实例一块面板）；
• 依赖关系：变量查询中引用其他变量时自动形成依赖与刷新顺序。

---

6. 统一告警（重点）

Grafana 8+ 的统一告警（Unified Alerting）支持跨数据源告警，且能作为 Alertmanager 的客户端发送通知。

6.1 告警架构与概念

Alert rules（规则，按 Evaluation group 分组周期评估）
    │ 触发
    ▼
Grafana Alertmanager（内置或对接外部 Alertmanager）
    │ 路由
    ▼
Notification policies（通知策略：分组、等待、重复间隔、路由树）
    │
    ▼
Contact points（接收器：邮件 / Webhook / 钉钉 / 飞书 / Slack / PagerDuty...）

关键概念：

概念	说明
Alert rule	一条告警规则：查询 + 条件 + 待确认时长（pending）
Evaluation group	规则按组统一评估周期（如每 1 分钟），同组顺序执行
Folder	规则存放在文件夹中，权限随文件夹
Contact point	通知出口
Notification policy	标签匹配 → 路由到哪个 contact point，含分组/间隔
Silence	临时静默（维护窗口）
Mute timings	固定时段不通知（如凌晨不发 warning）

6.2 创建告警规则（UI 全流程）

Alerting → Alert rules → New alert rule → Grafana managed alert：

Step 1：Define query and alert condition

[A] 数据源=Prometheus, 查询:
    sum(rate(http_requests_total{status=~"5.."}[$__rate_interval]))
    / sum(rate(http_requests_total[$__rate_interval]))
    模式: Instant（取当前值）
[B] 数据源=Expression, 类型=Reduce, 输入 A, 函数 Last
[C] 数据源=Expression, 类型=Threshold, 输入 B: IS ABOVE 0.05

即：A 查错误率 → B 归约为标量 → C 判断 > 5% 则触发。

Step 2：设置评估与待确认

Folder:            SRE
Evaluation group:  app-alerts (every 1m)
Pending period:    5m          # 持续满足 5 分钟才 Firing，防抖动

Step 3：Details（标签与注解）

Labels:      severity=critical, team=order
Annotations:
  summary:     订单服务错误率 {{ $values.C }} 超过 5%
  description: 当前值 {{ $values.B }}，请查看 Runbook。
  runbook_url: https://wiki.example.com/runbooks/order-5xx

Step 4：保存 。告警状态机：Normal → Pending → Firing（恢复后回到 Normal；还可配置 No Data / Error 时的行为：OK / Alerting / Keep Last State）。

6.3 通知策略（Notification policies）

Alerting → Contact points / Notification policies：

Root policy:
  receiver = default-webhook
  group_by = grafana_folder, alertname
  timings: group_wait=30s, group_interval=5m, repeat_interval=4h

Nested policy:
  matchers: severity = critical
  receiver = pager (电话/即时通知)
  repeat_interval = 1h

6.4 Contact Points 与中文生态（钉钉/飞书/企微）

内置 receiver：Email、Webhook、Slack、PagerDuty、Opsgenie、Telegram、Microsoft Teams、VictorOps 等。

国内常用做法------Webhook 中转机器人：

1. 搭建一个轻量转发服务（社区有大量 prometheus-webhook-dingtalk / 飞书机器人项目）；

2. Grafana 里新建 Contact point → 类型 Webhook：

   URL: http://dingtalk-webhook:8060/dingtalk/ops/send
   Message: 使用默认模板或自定义：
   [{{ .Status }}] {{ .CommonLabels.alertname }}
   {{ range .Alerts }}
   摘要: {{ .Annotations.summary }}
   详情: {{ .Annotations.description }}
   {{ end }}

6.5 静默与免打扰

• Silences ：Alerting → Silences → New，按匹配器（如 instance=xxx）+ 时间窗创建；
• Mute timings：定义重复时段（每周五 18:00 - 周一 9:00），挂到通知策略上，窗口内不发送（但告警仍记录）。

6.6 与 Prometheus Alertmanager 的关系（选型）

场景	建议
纯指标告警、团队已有 Prometheus	规则写在 Prometheus（Alertmanager 收口），Grafana 只展示
多数据源（指标+日志+SQL）统一告警	Grafana managed rules
两者混用	Grafana 规则可通过「外部 Alertmanager 数据源」把通知交给现有 AM 集群

6.7 告警规则 Provisioning（YAML 即代码）

/etc/grafana/provisioning/alerting/rules.yml：

apiVersion: 1
groups:
  - orgId: 1
    name: app-alerts
    folder: SRE
    interval: 1m
    rules:
      - uid: order-5xx-rate
        title: Order service 5xx rate too high
        condition: C
        data:
          - refId: A
            relativeTimeRange: { from: 300, to: 0 }
            datasourceUid: prometheus
            model:
              expr: |
                sum(rate(http_requests_total{status=~"5.."}[$__rate_interval]))
                / sum(rate(http_requests_total[$__rate_interval]))
              instant: true
          - refId: B
            datasourceUid: __expr__
            model: { type: reduce, reducer: last, expression: A }
          - refId: C
            datasourceUid: __expr__
            model: { type: threshold, expression: B,
                     conditions: [{ evaluator: { type: gt, params: [0.05] } }] }
        noDataState: NoData
        execErrState: Error
        for: 5m
        labels: { severity: critical }
        annotations:
          summary: "订单服务 5xx 错误率 {{ $values.C }} 超过 5%"

12+ 的 Observability as Code 还支持把规则/仪表盘与 Git 仓库双向同步（Connections → Git sync）。

---

7. 用户与权限管理

7.1 权限模型概览

Organization（组织，独立的数据源/仪表盘空间）
 └── Team（团队）
      └── User（用户，组织内角色）
           └── Folder / Dashboard / Data source 级权限

组织内角色：

角色	权限
Admin	组织内一切（用户、数据源、设置）
Editor	创建/编辑仪表盘与告警，不能管理用户和数据源配置
Viewer	只读（可查询、看图）
Admin/Editor/Viewer（文件夹级）	对单个 Folder 细化授权

7.2 常用管理操作

• 用户：Administration → Users → Invite（邮件邀请或直接创建）；
• 团队：Administration → Teams，把人分组后对 Folder 授权给团队而非个人；
• Service Accounts ：Administration → Service accounts，为 CI/脚本/API 集成创建专用账号，生成 API Token（替代已废弃的全局 API Keys）；
• RBAC（Enterprise）：细粒度角色，如「只能编辑某文件夹下的告警规则」。

7.3 认证方式

支持本地账号、LDAP（/etc/grafana/ldap.toml）、OAuth（GitHub/Google/GitLab/通用 OIDC）、SAML（Enterprise）。OIDC 示例：

[auth.generic_oauth]
enabled = true
name = SSO
client_id = grafana
client_secret = xxx
scopes = openid profile email
auth_url = https://sso.example.com/oauth/authorize
token_url = https://sso.example.com/oauth/token
api_url = https://sso.example.com/userinfo
role_attribute_path = contains(roles[*], 'admin') && 'Admin' || 'Viewer'

---

8. Dashboard as Code 与 HTTP API

8.1 导入 / 导出

• 导入：Dashboards → New → Import，粘贴 JSON 或输入 grafana.com 的 Dashboard ID（如 1860）；导入时可重映射数据源；
• 导出 ：Dashboard settings → JSON Model 复制，或面板顶部 Share → Export（勾选 Export for sharing externally 会把 $__inputs 参数化，便于他人导入）。

8.2 Provisioning 仪表盘（文件即仪表盘）

/etc/grafana/provisioning/dashboards/dashboards.yml：

apiVersion: 1
providers:
  - name: default
    folder: SRE                 # 目标文件夹
    type: file
    updateIntervalSeconds: 30   # 轮询间隔
    allowUiUpdates: true        # 允许 UI 修改（不持久化回文件）
    options:
      path: /etc/grafana/dashboards
      foldersFromFilesStructure: false

把仪表盘 JSON 放入 /etc/grafana/dashboards/ 即自动加载，配合 Git 管理实现仪表盘版本化。

8.3 HTTP API 常用操作

先创建 Service account token（glsa_xxx），然后：

# 1) 列出仪表盘
curl -H "Authorization: Bearer glsa_xxx" \
  http://grafana:3000/api/search?type=dash-db

# 2) 按 UID 获取仪表盘定义
curl -H "Authorization: Bearer glsa_xxx" \
  http://grafana:3000/api/dashboards/uid/abc123

# 3) 创建/更新仪表盘（overwrite 覆盖）
curl -X POST -H "Authorization: Bearer glsa_xxx" \
  -H "Content-Type: application/json" \
  -d '{"dashboard": {...JSON...}, "folderId": 1, "overwrite": true}' \
  http://grafana:3000/api/dashboards/db

# 4) 通过数据源代理直接查询（不必暴露 Prometheus 端口）
curl -H "Authorization: Bearer glsa_xxx" \
  -G --data-urlencode 'query=up' \
  "http://grafana:3000/api/datasources/proxy/uid/prometheus/api/v1/query"

# 5) 渲染面板为 PNG（需 image renderer 插件）
curl -H "Authorization: Bearer glsa_xxx" \
  "http://grafana:3000/render/d-solo/abc123/my-dash?panelId=2&width=1000&height=500" \
  -o panel.png

8.4 生态工具

• Grafonnet（官方）：Jsonnet 库，代码化生成仪表盘；
• Terraform grafana provider：管理仪表盘/数据源/告警/文件夹；
• Git sync（12+）：官方原生双向同步（Connections → Git sync）；
• grizzly：CLI 工具，拉取/推送/比对 Grafana 资源。

---

9. Explore 与日志/链路关联

Explore 是面向排障的交互式查询界面（左侧罗盘图标）：

• 即时查询：无仪表盘负担，支持查询历史、拆分对比（Split）、录制查询为面板；

• LogQL 示例：

  {app="order-service"} |= "ERROR" | json | level="error"
  sum by (app) (count_over_time({app="order-service"} |= "timeout" [5m]))

可观测性三支柱联动（推荐配置）：

1. Logs → Metrics ：Loki 数据源开启 Derived fields ，正则提取 traceID 生成链接跳 Tempo；
2. Logs → Trace ：日志面板点击 traceID 直接打开链路瀑布图；
3. Metrics → Trace ：Prometheus 数据源配置 Exemplars，Time series 面板上的菱形点可跳转对应链路；
4. Trace → Logs ：Tempo 数据源配置 Traces to logs（用 span 的 service/name 标签反查 Loki）。

配合 12+ 的 Drilldown 应用（Metrics/Logs/Profiles/Traces），可从总览一路下钻到单实例单日志行。

---

10. 插件生态

10.1 插件类型

类型	说明	例子
Panel	新可视化	ECharts、FlowCharting、Polystat
Data source	新数据源	Zabbix、Infinity、ClickHouse、MongoDB
App	套件（面板+数据源+页面）	Synthetic Monitoring、Traces 应用

10.2 安装方式

# CLI（服务器端安装后重启）
grafana-cli plugins install alexanderzobnin-zabbix-app
grafana-cli plugins list-remote
systemctl restart grafana-server

或在 UI：Administration → Plugins and data → 搜索安装。

自研/私有插件需放入 plugins 目录并在 grafana.ini 配置：

allow_loading_unsigned_plugins = my-custom-panel

10.3 常用插件推荐

• alexanderzobnin-zabbix-app：让 Grafana 直连 Zabbix；
• yesoreyeram-infinity-datasource：万能 JSON/REST/CSV/GraphQL 数据源；
• grafana-image-renderer：告警邮件附图、渲染 PNG；
• flant-statusmap-panel / volkovlabs-echarts-panel：特殊图表需求。

---

11. 性能优化与最佳实践

11.1 查询性能（仪表盘卡顿的根因几乎都在查询）

1. 步长自适应 ：区间用 $__rate_interval / $__interval，不要在长时间范围里跑 15s 固定步长；
2. 减少序列数 ：sum/topk 聚合后再画图；避免 {__name__=~".+"} 类全量查询；
3. 预聚合 ：高频大查询在 Prometheus 侧写 recording rules，面板查结果指标；
4. Instant 查询：Stat/Table 面板用 Instant 而非 Range；
5. 控制面板数：单仪表盘面板 > 30 时考虑拆分或用 Row 折叠（Collapsed row 不预加载）；
6. 时间范围：长范围看趋势时配合降采样数据源（Thanos 降采样、VM 的 rollup）。

11.2 可视化规范

• 单位必配：bytes/s、percent、reqps，避免「裸数字」误导；
• 阈值着色统一：团队约定绿/黄/红分档含义并保持一致；
• 命名 ：面板标题写清「对象 + 指标 + 单位」，如 API 网关 P99 延迟 (ms)；
• 仪表盘分层：L1 总览（Stat/红绿灯）→ L2 服务级（RED 三件套）→ L3 实例级（CPU/内存/IO），用 Data links 串联；
• 每个告警有对应面板 ：告警 annotation 里放仪表盘链接（?from=now-1h&to=now&var-instance={``{ $labels.instance }}）。

11.3 安全与分享

• 生产关闭匿名访问与自助注册；嵌入第三方系统用 Public Dashboards （只读、可加注解开关）或快照 Snapshot（静态导出，不含实时数据）；
• 数据源密码放 secureJsonData / 环境变量，不要明文写在 dashboard JSON；
• 对外反代加 root_url 与 TLS，cookie_secure = true。

---

12. 常见问题排查（FAQ）

Q1：面板显示 No data / 空白？

① 时间范围对不对；② 查询在数据源原生界面（Prometheus UI）能否出数；③ 变量没选中值（检查下拉框是否为空）；④ $__interval 在超长范围时变大导致稀疏------显式设 min step 或改查询；⑤ 数据源时区/时钟漂移。

Q2：导入别人的仪表盘报错/缺数据源？

导入时给每个 $__inputs 选择本机存在的数据源；确认导出时勾选了 for sharing externally；缺面板插件时先安装对应插件。

Q3：告警触发了但没收到通知？

Alerting → Contact points 测试发送 → 检查 Notification policy 是否匹配到该规则的标签（默认走 root policy）→ 查看 Alerting → Contact points 的通知历史与日志；注意 group_wait/repeat_interval 造成的延迟。

Q4：仪表盘加载特别慢？

按 11.1 排查：先看慢在哪条查询（面板右上角 → Query inspector → Refresh 看每条查询耗时），再做聚合/降采样/拆面板。

Q5：时区显示不对？

Grafana 默认用浏览器时区。Dashboard settings → General 可强制时区；数据源（如 MySQL）注意自身时区设置。

Q6：忘记 admin 密码？

grafana-cli admin reset-admin-password '新密码'   # 需能访问数据库文件

Q7：中文邮件乱码/中文搜索不到？

邮件模板用 UTF-8；中文搜索正常支持，但注意标签/名称含空格时需引号；截图中文乱码是渲染容器缺字体，给 image-renderer 安装 fonts-noto-cjk。

Q8：容器升级后仪表盘丢了？

确认数据卷 /var/lib/grafana 有持久化；sqlite 损坏时从备份恢复。生产建议 dashboard provisioning + Git 管理，不依赖数据库单点。

Q9：Grafana 与 Prometheus 的告警重复了？

明确分工（见 6.6）：Prometheus Alertmanager 管基础设施告警，Grafana 管业务/跨源告警；或用外部 label（如 source=grafana）区分，避免同一故障双份轰炸。

Q10：如何批量迁移仪表盘到新环境？

① 少量：Export JSON → Import；② 批量：用 API 脚本拉取 /api/search + /api/dashboards/uid/* 再 POST 到新环境；③ 长期：provisioning/Git 管理，新环境直接挂载同一仓库。

---