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. ID より UID を使用する：UID は Grafana インスタンス間で持ち運びできます
2. 更新時にバージョンを含める：同時に行われた変更の上書きを防ぎます
3. overwrite: true は慎重に使用する：強制的に更新したい場合にのみ使用します
4. API キーよりサービスアカウントを使用する：新しいバージョンの Grafana では API キーは非推奨です

---

注意点

• データソースの権限：データソースにチームごとの明示的な権限が設定されていると、閲覧者にはパネルが表示されても「query forbidden」が表示されます。管理者以外のユーザーには分かりにくい問題です。
• 変数の補間：$__interval と $__name は、従来のクエリバックエンドと新しいクエリバックエンドで解釈が異なるため、同じダッシュボード JSON でも動作が異なります。
• /etc/grafana/provisioning 配下の YAML によるデータソースのプロビジョニング：UI からの編集は、ファイルの再読み込み時に通知なく元に戻されます。信頼できる情報源を一つに決めてください。
• API トークンは組織ごとです。複数組織の Grafana 環境では個別のトークンが必要です。グローバルな「admin」トークンでも組織をまたいで使用することはできません。
• 時間フィールドが欠落したアノテーションクエリは、エラーにならずアノテーションを 0 件返します。パネルではなく、クエリの生のレスポンスを確認してデバッグしてください。
• アラートルールの状態は Prometheus ではなく Grafana の DB に保存されます。Grafana を以前のバージョンに戻すと、アラート状態の履歴が失われます。