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": "..." } → working
   # { "status": "ERROR", ... } → URL unreachable or auth misconfigured
   

创建服务账户和令牌

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 → token + role assignment work
   # 401 → token wrong; 403 → role wrong
   

仪表板预置

# 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: optional ISO 8601 timestamp; omit for no-expiry tokens

（具有精细权限的自定义 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／身份验证／安全／功能开关配置，以及需要重启才能生效的问题