手写仪表板 JSON 无法扩展,而从 UI 导出又让 UI 成了真正的事实来源。Grafana 的可观测性即代码工具同时解决了这两个问题:Foundation SDK 用类型化代码生成仪表板,Git Sync 让 Grafana 在 Git 仓库中读写仪表板,gcx CLI 则从终端推送和拉取资源。其中有些功能比较新,有些 API 被标记为 alpha,所以请查阅你所用版本的文档。

使用 Foundation SDK 生成仪表板

Foundation SDK 为 Go、TypeScript、Python、PHP 和 Java 提供了仪表板、面板和查询的构建器。你用类型化语言描述仪表板,调用 build() 就会产出仪表板 JSON。因为它是代码,你可以获得编译期检查、复用(例如一个构建标准服务面板行的函数),以及正常的代码审查。

为你的语言安装它,例如:

# Go
go get github.com/grafana/grafana-foundation-sdk/go@latest

# TypeScript
npm install @grafana/grafana-foundation-sdk

Python、PHP 和 Java 的包在 SDK 文档中列出。它面向 Grafana 10 及更高版本。

一个典型的工作流:

1. 编写一个小程序来定义仪表板,并将每个仪表板的 JSON 写入 dashboards/<name>.json。
2. 在 CI 中运行它。
3. 提交生成的 JSON,或将其作为构建产物发布。
4. 通过你已在使用的任何机制交付该 JSON:provider 文件夹、ConfigMap、GrafanaDashboard 资源、Terraform 或 Git Sync。

# CI job sketch
steps:
  - run: npm ci
  - run: npx tsx dashboards/generate.ts --out dashboards/generated
  - run: git diff --exit-code dashboards/generated   # fail if generated files are stale

git diff --exit-code 检查确保没有人手工编辑生成的 JSON,并且代码与输出保持同步。

Git Sync

Git Sync 让 Grafana 将仪表板以 JSON 形式存储在 Git 仓库中。变更是双向流动的:在 Grafana UI 中的编辑会变成一次提交或拉取请求,而仓库中合并的变更会出现在 Grafana 中。Grafana 默认每 60 秒轮询一次仓库,使用 webhook 则几乎可以立即更新。Git Sync 在 Grafana 13 的各个版本中均已正式可用。它支持 GitHub(使用 App 认证)、GitHub Enterprise、GitLab、Bitbucket,以及通过 “Pure Git” 仓库类型支持的普通 Git。

你可以完全以代码方式用 Repository 资源来配置它。创建 repository.yaml:

apiVersion: provisioning.grafana.app/v0alpha1
kind: Repository
metadata:
  name: my-repo
spec:
  title: My Repository
  type: github
  github:
    url: https://github.com/<org>/<repo>
    branch: main
    path: grafana/
  sync:
    enabled: true
    intervalSeconds: 60
    target: folder
  workflows:
    - write
    - branch
secure:
  token:
    create: '<git-personal-access-token>'

字段说明:

• type 是 github、githubEnterprise、gitlab、bitbucket 或 git 之一,每种都有自己的块。Bitbucket 和普通 Git 还需要 tokenUser。
• path 是仓库中由 Grafana 所拥有的文件夹。
• workflows 控制 UI 保存时的行为:write 直接提交到分支,branch 则打开一个拉取请求。
• sync.target 是 folder(默认)或 folderless。
• secure.token 携带凭据,因此它被存为 secret,而不是放在 spec 中。你也可以使用 GitHub App 或 OAuth app 连接,通过 spec.connection.name 来替代令牌;这些需要单独的 connection.yaml。
• API 版本是 v0alpha1,所以字段名称可能在版本之间变化。

用 gcx(见下一节)应用它,或者如果你愿意,也可以通过 Grafana UI。

Git Sync 最擅长的是:让 UI 作者和以 Git 为先的工程师共享一个事实来源,并让每一次变更都经过拉取请求审查。在为大型实例采用它之前,请阅读使用限制页面,因为 provision 大量仪表板存在性能方面的考虑。

gcx CLI

gcx 是 Grafana 用于处理资源的命令行工具,在 Grafana Cloud 上还可用于其他产品。它可用于 Grafana Cloud 以及开源版或 Enterprise 的 Grafana 12 及更高版本,并取代了之前的 grafanactl 工具(迁移主要是重命名命令,grafanactl resources serve 变成 gcx dev serve)。请从项目仓库安装它,并按其文档用你的 Grafana URL 和令牌配置一个 context。

常用命令:

# push local resource files to Grafana
gcx resources push --path ./resources

# list what exists, or inspect one resource
gcx resources get repositories
gcx resources get repository/my-repo -o yaml

# edit or delete
gcx resources edit repository/my-repo
gcx resources delete repository/my-repo

# live-preview dashboards while developing
gcx dev serve

在 CI 中用它从仓库推送资源定义,或者在本地用 SDK 构建仪表板时使用它。

在各种方式之间选择

情形	选用
许多相似的仪表板,或可复用的构件	Foundation SDK,通过任意机制交付
作者在 UI 中工作,但你希望以 Git 作为记录	Git Sync
Kubernetes GitOps,每个仪表板一个对象	Grafana Operator
包含团队和权限在内的整个平台自动化	Terraform
一个 Grafana,静态 JSON 文件	普通的 provider 文件夹

它们可以很好地组合:用 SDK 生成 JSON,提交到仓库,然后让 Git Sync 或 provider 文件夹来交付。

验证

gcx resources get repositories
curl -s -u admin:$GRAFANA_ADMIN_PASSWORD \
  "http://localhost:3000/api/search?type=dash-db" | jq '.[] | {title, folderTitle}'

对于仓库同步问题,请在 Grafana 中检查仓库的状态(在 Administration 下的 Provisioning),以及 Grafana 服务器日志。典型的问题包括令牌过期、分支或路径错误,以及 Grafana 无法访问的 webhook。