Contents
Grafana Agentの導入・設定手順と実務での運用準備ガイド
Grafana Agentは、現代のITインフラにおける監視と運用効率化を支える重要なツールです。本記事ではLinux/Windows環境ごとのインストール方法やconfigmap.yamlの構成、トレース・メトリクス・ログの集約設定に焦点を当てて、Grafana Agent 設定 手順に関する詳細な解説を行います。導入後のエラー対処法も網羅しており、DevOpsエンジニアやシステム管理者が実務で即活用できる情報を提供します。
導入前の準備と環境確認
Grafana Agentの導入には、OS要件や前提ソフトウェアの事前確認が不可欠です。LinuxではUbuntu 20.04以上またはCentOS Stream 8が推奨され、Windows環境ではWindows Server 2019以降が必要です。また、Linuxにはcurlやjqなどのコマンドラインツール、Windowsには.NET Frameworkの最新版がインストールされていることを事前に確認してください。
既存の監視ツール（例: Prometheus、ELKスタック）と競合しないように、Agentのロギング先やメトリクス送信先のポート設定に注意が必要です。サービスディスカバリー機能の有無やネットワークファイアウォール設定も事前にチェックすることで、導入後のトラブルを回避できます。
インストール方法の選択
パッケージ管理でのインストール手順
Linux環境ではAPT/YUM経由で簡単なインストールが可能です。以下にUbuntuの例を示します：
-
リポジトリ登録
curl -fsSL https://grafana.com/api/installations/grafana-agent | sudo tee /etc/apt/sources.list.d/grafana-agent.list
curl -fsSL https://grafana.com/KEYS | gpg --dearmor > grafana.gpg
sudo mv grafana.gpg /usr/share/keyrings/ -
パッケージインストール
sudo apt update && sudo apt install grafana-agent -y
Windowsの場合、MSIパッケージをダウンロードしてインストーラーを実行することで導入可能です。ただし、サービス起動時のエラーログはC:\ProgramData\Grafana\logs\agent.logに保存されているため、失敗時に参照する必要があります。
バイナリ配布による導入フロー
Linux環境では公式サイトからバイナリをダウンロードし、以下のように手動で導入できます：
-
バイナリファイルの取得
wget https://grafana.com/agent/releases/latest/grafana-agent-linux-amd64.tar.gz
tar -xzf grafana-agent-linux-amd64.tar.gz -
起動スクリプトの設定
./bin/grafana-agentを実行し、--config.fileオプションで配置先を指定します。WindowsではPowerShellから同等のコマンドを使用可能ですが、サービスとして登録する場合はSCコマンドを使う必要があります。
configmap.yaml の基本構成項目
Agentの基本設定セクション
Agentの動作に必要な基本的な設定はconfigmap.yamlで定義します。以下が主要な項目です：
| 項目名 | 値例 | 補足 |
|---|---|---|
agent.name |
my-agent-instance |
エージェントの識別名 |
agent.id |
1234567890abcdef1234567890ab |
一意なUUID形式で指定 |
server.grpc_listen |
localhost:12345 |
内部通信に使用するポート |
データ収集モジュールの有効化方法
トレースやメトリクス、ログを集めるモジュールを有効にするには、以下のような構成を追加します：
|
1 2 3 4 5 6 7 8 9 |
metrics: enable: true otlp: endpoint: "https://otel-collector.example.com:4317" traces: enable: true logs: enable: true |
Windows環境ではイベントロガーとの連携が必要な場合があり、windows_event_logsセクションを記述することで特定のログカテゴリー（例: System, Application）を収集できます。
トレース・メトリクス・ログの集約設定
OTLPエンドポイントの指定方法
データをGrafanaに送信するには、OTLPエンドポイントを明示的に設定します。以下はLinuxとWindows共通の構成例です：
|
1 2 3 4 5 |
otlp: endpoint: "https://otel-collector.grafana.com:4317" headers: Authorization: Bearer <API_KEY> |
この際、TLS証明書の有効期限や接続先ホスト名との一致を確認し、証明書エラーを防ぐことが重要です。
ログレベルの階層制御
ログ出力の詳細度はlog_levelパラメータで調整可能です。以下のように設定することで、トラブルシューティング時の情報量をコントロールできます：
|
1 2 3 |
agent: log_level: "debug" |
Linuxではデバッグログが/var/log/grafana-agent.logに保存され、WindowsではC:\ProgramData\Grafana\logs\agent.logとなります。
Grafanaとの連携手順
APIキーの発行と権限設定
AgentからGrafanaへ通信する際には、APIキーを事前に発行しておく必要があります。GrafanaのUIから「API Keys」セクションで「Create API Key」と選択し、Read-Writeの権限を付与します。
⚠️ 注意: 権限が過剰に設定されていると情報漏洩リスクがあります。最小限の権限で運用することを推奨します。
ダッシュボードテンプレートの適用
Grafana側では、Agentから送信されるメトリクスやトレースデータを可視化するためのダッシュボードテンプレートが必要です。公式リポジトリからダウンロードした.jsonファイルを「Import」画面でインポートすることで利用可能です。
接続確認コマンドとして、以下を実行するとエンドポイントとの通信が成功しているかをチェックできます：
|
1 2 |
curl -k https://otel-collector.grafana.com:4317 |
セキュリティ設定とよくあるエラー対処法
TLS証明書の正規性チェック
AgentからGrafanaへの接続はTLS 1.2以上で暗号化されるため、証明書の有効性を確認する必要があります。以下のようにopensslコマンドで検証できます：
|
1 2 |
openssl s_client -connect otel-collector.grafana.com:4317 -showcerts |
証明書が失効している場合、Verify return code: 20 (unable to get local issuer certificate)などのエラーが発生します。この際、CA証明書を更新するか、insecure_skip_verify: trueで一時的に無視する設定（非推奨）もあります。
認証失敗時のログ解析手順
認証に失敗した場合のエラーは通常、Authorization failedやinvalid tokenといったメッセージがログに記録されます。以下のような手順でトラブルシューティングを行ってください：
- APIキーの有効性を再確認
- 時限付きキーの期限切れチェック
-
ロール・権限の誤設定
-
証明書やタイムゾーン設定の確認
-
TLS証明書の正規性や日付同期（NTP）による時間ズレを疑う
-
接続先ホストのDNS設定
otel-collector.grafana.comが正しいDNSに解決しているかをnslookupで確認する
Windows環境では、サービスアカウントの権限不足やセキュリティソフトによる通信遮断も考えられるため、セキュリティポリシーの見直しが必要なケースがあります。
まとめ
本記事ではGrafana AgentをLinux/Windows環境で導入・設定するにあたって必要な手順とポイントを解説しました。重要な点は以下の通りです：
- インストール方法（パッケージ管理 / バイナリ配布）の選択
- configmap.yamlでの基本設定とデータ収集モジュールの有効化
- OTLPエンドポイントの指定やログレベル設定による集約精度の向上
- GrafanaとのAPIキー連携およびダッシュボードテンプレート適用
- TLS証明書・認証情報管理などセキュリティ対策
導入後は、コメント欄に遭遇したエラーメッセージを共有いただけると、今後の記事改善やFAQの充実につながります。