grafana

grafana

目的

Grafana は、さまざまなデータソースのメトリクス、ログ、トレースを可視化し、クエリを実行できるオープンソースのプラットフォームです。インタラクティブなダッシュボードの作成、アラートの設定、データの探索を通じて、システムを効果的に監視できます。

使用する場面

インフラストラクチャ、アプリケーション、サービスをリアルタイムで監視するために、カスタムダッシュボードを構築する必要がある場合に Grafana を使用します。Kubernetes のメトリクスの追跡、サーバーログの分析、分散システムのトレースの関連付けなど、可観測性に関わるシナリオに最適です。単純な静的レポートには適していません。動的なクエリと可視化が必要な場合に使用してください。

主な機能

• グラフ、テーブル、ゲージ用のパネルを備えたダッシュボードを作成、管理できます。
• プラグインを介して、Prometheus、Loki、Elasticsearch などのデータソースと統合できます。
• メトリクスやログのしきい値に基づくアラートルールを設定できます。
• PromQL などのクエリ言語を使用したアドホッククエリとデータ探索に対応しています。
• ダッシュボードとデータを保護するためのロールベースアクセス制御（RBAC）を利用できます。
• バージョン管理のため、ダッシュボードを JSON 形式でエクスポート／インポートできます。

使用パターン

Grafana をサーバーとして実行するには、設定ファイルを指定して起動し、設定ファイルのパスとバインドするポートを指定します。自動化するには、API を使ってダッシュボードをプログラムから作成します。一般的なパターンとして、Prometheus からデータを取り込み、Grafana の UI または API を介してクエリを実行します。CI/CD では、ワークフローに Grafana を組み込み、必要に応じてダッシュボードを生成します。スケーラビリティを確保するため、公式イメージを使った Docker などのコンテナー環境で常に実行してください。

主なコマンド／API

管理タスクには Grafana CLI を使用します。サーバーを起動するには、grafana-server --config /etc/grafana/grafana.ini --homepath /usr/share/grafana を実行します。プラグインをインストールするには、grafana-cli plugins install <plugin-name> を実行します。

API エンドポイントでは、API キーによる認証が必要です。キーを環境変数として設定します：export GRAFANA_API_KEY=$YOUR_API_KEY。その後、curl を使用してリクエストを送信します。

例：API を介してダッシュボードを作成する：

curl -H "Authorization: Bearer $GRAFANA_API_KEY" -X POST https://your-grafana-instance/api/dashboards/db -d '{"dashboard": {"id": null, "uid": null, "title": "New Dashboard", "tags": ["example"], "timezone": "browser", "panels": []}, "folderId": 0, "overwrite": false}'

データソースにクエリを実行する：GET https://your-grafana-instance/api/datasources/1。設定ファイルは INI 形式です。例：

[server]
http_port = 3000

統合に関する注意

UI または設定を使ってデータソースを追加し、Grafana と統合します。Prometheus の場合は、URL に http://prometheus:9090 を指定してデータソースを追加し、必要に応じて基本認証を有効にします。シークレットには環境変数を使用します。例：GF_SECURITY_ADMIN_PASSWORD=$ADMIN_PASSWORD。アラートを設定するには、設定ファイルで Slack や PagerDuty などの通知チャネルにリンクします：grafana.ini の [alerting] セクションに追加してください。

ほかのツールに埋め込むには、ダッシュボードの iframe 埋め込みオプションを使用します。コード統合では、Terraform に Grafana ダッシュボードをインポートします。resource "grafana_dashboard" "example" { config_json = file("dashboard.json") } のようなリソースを定義します。次のような Grafana のプロビジョニング用 YAML ファイルを使って、先にデータソースをプロビジョニングしてください：

apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090

エラー処理

よくあるエラーには、データソースへの接続失敗があります。journalctl -u grafana-server でログを確認するか、UI の Server Admin > Logs で確認してください。API エラー（例：401 Unauthorized）が発生した場合は、echo $GRAFANA_API_KEY で API キーを確認し、有効期限が切れていないことを確認してください。クエリエラーに対処するには、Python では次のように、API 呼び出しを try-catch ブロックで囲みます：

import requests
try:
    response = requests.post('https://your-grafana-instance/api/dashboards/db', headers={'Authorization': f'Bearer {os.environ["GRAFANA_API_KEY"]}'}, json=data)
    response.raise_for_status()
except requests.exceptions.HTTPError as err:
    print(f"Error: {err.response.status_code} - {err.response.text}")

設定に問題がある場合は、grafana-server --config /path/to/config.ini --verify-config で grafana.ini を検証します。

具体的な使用例

例 1：基本的な Prometheus ダッシュボードを設定します。まず、Grafana を起動します：docker run -d -p 3000:3000 grafana/grafana。ログインし（デフォルトのユーザー名：admin、パスワード：admin）、UI からデータソースを追加します：Configuration > Data Sources > Add Prometheus に移動し、URL に http://your-prometheus-url:9090 を指定します。ダッシュボードを作成します：クエリ up{job="prometheus"} を使ったパネルを追加し、保存します。

例 2：API を介してアラートの作成を自動化します。API キーを環境変数にエクスポートします：export GRAFANA_API_KEY=your_key。アラートルールを作成するリクエストを送信します：

curl -H "Authorization: Bearer $GRAFANA_API_KEY" -X POST https://your-grafana-instance/api/ruler/grafana/default -d '{"name": "High CPU Alert", "condition": "A", "for": "5m", "query": {"params": ["avg", "up", "{job=\"node\"}"], "model": {}}}'

これにより、メトリクスに基づいて CPU 使用率が高い場合のアラートが設定されます。

グラフの関係

• 関連：devops-sre クラスターの一部として、Prometheus（メトリクスデータを提供）、Loki（ログを処理）と関連しています。
• 接続先：Elasticsearch（ログの可視化用）、Jaeger／Zipkin（トレース用）。
• 依存関係：オブザーバビリティのワークフロー全体を実現するため、Alertmanager などの監視ツールと組み合わせて使用されることがよくあります。