grafana

grafana-skill

使用 TypeScript 工具和 HTTP API 工作流，以编程方式管理 Grafana 资源。

工作流路由

工作流	触发条件	文件
DashboardCrud	“创建仪表板”、“更新仪表板”、“删除仪表板”、“列出仪表板”、“导出仪表板”	Tools/DashboardCrud.ts
GrafanaClient	“grafana API”、“grafana 客户端”、“TypeScript grafana”	Tools/GrafanaClient.ts
ApiReference	“grafana API 参考”、“grafana 端点”	References/

工具

DashboardCrud CLI

# Set environment variables
export GRAFANA_URL="https://grafana.example.com"
export GRAFANA_TOKEN="your-service-account-token"

# List dashboards
bun run Tools/DashboardCrud.ts list
bun run Tools/DashboardCrud.ts list --query production --tag monitoring

# Get dashboard by UID
bun run Tools/DashboardCrud.ts get abc123

# Export dashboard to JSON
bun run Tools/DashboardCrud.ts export abc123 --output dashboard.json

# Create dashboard from JSON file
bun run Tools/DashboardCrud.ts create --file dashboard.json --folder my-folder

# Update dashboard
bun run Tools/DashboardCrud.ts update abc123 --file updated.json --message "Updated panels"

# Clone dashboard
bun run Tools/DashboardCrud.ts clone abc123 --title "Production Copy" --folder prod-folder

# View version history
bun run Tools/DashboardCrud.ts versions abc123

# Restore to previous version
bun run Tools/DashboardCrud.ts restore abc123 --version 5

# Delete dashboard
bun run Tools/DashboardCrud.ts delete abc123

GrafanaClient TypeScript 库

import { GrafanaClient, createGrafanaClient } from './Tools/GrafanaClient';

// Initialize from environment variables
const client = createGrafanaClient();

// Or with explicit config
const client = new GrafanaClient({
  baseUrl: 'https://grafana.example.com',
  token: 'your-service-account-token',
  orgId: 1, // optional
});

// Dashboard operations
const dashboards = await client.searchDashboards({ query: 'production', tag: 'monitoring' });
const dashboard = await client.getDashboardByUid('abc123');
const saved = await client.saveDashboard({ dashboard: myDashboard, folderUid: 'folder-uid' });
await client.deleteDashboard('abc123');

// Version management
const versions = await client.getDashboardVersions('abc123');
await client.restoreDashboardVersion('abc123', 5);

// Folders, Data sources, Alerting, Annotations also available

身份验证

# Service Account Token (Recommended)
export GRAFANA_TOKEN="glsa_xxxxxxxxxxxxxxxxxxxx"

# Multi-Organization Header
curl -H "Authorization: Bearer $GRAFANA_TOKEN" \
     -H "X-Grafana-Org-Id: 2" \
     https://grafana.example.com/api/org

API 快速参考

资源	列出	获取	创建	更新	删除
仪表板	GET /api/search	GET /api/dashboards/uid/:uid	POST /api/dashboards/db	POST /api/dashboards/db	DELETE /api/dashboards/uid/:uid
文件夹	GET /api/folders	GET /api/folders/:uid	POST /api/folders	PUT /api/folders/:uid	DELETE /api/folders/:uid
数据源	GET /api/datasources	GET /api/datasources/uid/:uid	POST /api/datasources	PUT /api/datasources/uid/:uid	DELETE /api/datasources/uid/:uid
告警规则	GET /api/v1/provisioning/alert-rules	GET /api/v1/provisioning/alert-rules/:uid	POST /api/v1/provisioning/alert-rules	PUT /api/v1/provisioning/alert-rules/:uid	DELETE /api/v1/provisioning/alert-rules/:uid

参考文档

• 仪表板：完整的仪表板 CRUD、版本和权限
• 数据源：数据源管理、查询和健康检查
• 告警：告警规则、联系点和通知策略
• 文件夹：文件夹管理和权限
• 注释：创建、查询和更新注释
• 用户与团队：用户管理和团队操作
• 常见模式：错误处理、分页和实用工具

示例

示例 1：列出并导出仪表板

User: "List all production dashboards and export them"
→ bun run Tools/DashboardCrud.ts list --tag production
→ For each: bun run Tools/DashboardCrud.ts export <uid>
→ Returns list of exported JSON files

示例 2：从 JSON 创建仪表板

User: "Create a new dashboard from this JSON file"
→ bun run Tools/DashboardCrud.ts create --file dashboard.json --folder monitoring
→ Returns new dashboard UID and URL

示例 3：将仪表板克隆到另一个文件夹

User: "Clone the CPU dashboard to the production folder"
→ bun run Tools/DashboardCrud.ts clone cpu-uid --title "CPU Prod" --folder prod-folder
→ Returns cloned dashboard details

示例 4：恢复仪表板版本

User: "Restore dashboard abc123 to version 5"
→ bun run Tools/DashboardCrud.ts versions abc123
→ bun run Tools/DashboardCrud.ts restore abc123 --version 5
→ Dashboard restored, new version created

示例 5：以编程方式批量更新

User: "Write TypeScript to bulk update dashboard tags"
→ Uses GrafanaClient library:
   const client = createGrafanaClient();
   const dashboards = await client.searchDashboards({ tag: 'old-tag' });
   for (const dash of dashboards) {
     const full = await client.getDashboardByUid(dash.uid);
     full.dashboard.tags = full.dashboard.tags.filter(t => t !== 'old-tag');
     full.dashboard.tags.push('new-tag');
     await client.saveDashboard({ dashboard: full.dashboard, message: 'Updated tags' });
   }

错误处理

代码	描述
200	成功
400	错误请求（JSON 无效、缺少必填字段）
401	未授权（令牌无效或缺失）
403	禁止访问（权限不足）
404	未找到
409	冲突（资源已存在）
412	前置条件失败（版本不匹配）

提示

1. 优先使用 UID 而非 ID：UID 可跨 Grafana 实例移植
2. 更新时包含版本号：防止覆盖并发更改
3. 谨慎使用 overwrite: true：仅在需要强制更新时使用
4. 优先使用服务账号而非 API 密钥：较新版本的 Grafana 已弃用 API 密钥

---

注意事项

• 数据源权限：查看者可以看到面板，但如果数据源设置了明确的团队权限，就会收到“query forbidden”（查询被禁止）错误；非管理员用户对此容易感到困惑。
• 变量插值：$__interval 和 $__name 在旧版与新版查询后端中的解释方式不同；相同的仪表板 JSON 可能表现不同。
• 通过 /etc/grafana/provisioning 下的 YAML 配置数据源：通过 UI 所做的修改会在重新读取文件时被静默还原；请确定唯一的真实数据来源。
• API 令牌按组织划分——多组织 Grafana 部署需要使用单独的令牌；全局“admin”令牌无法跨组织使用。
• 缺少时间字段的注释查询会返回零条注释，但不会报错——请检查原始查询响应，而不是面板，以进行调试。
• 告警规则状态存储在 Grafana 数据库中，而非 Prometheus 中——回滚 Grafana 会丢失告警状态历史记录。