Contents
対象読者への導入
Grafana OpenTelemetry プラグインの設定方法を検索された方には、現在の公式手順とトラブルシューティング手法が求められているでしょう。本記事では、Grafana v10.x環境でのOpenTelemetryプラグイン導入からダッシュボード構築まで、実務で即戦力となる具体的な手順を解説します。導入ミスの多い設定ポイントや最新バージョン対応の注意点も網羅し、読者の悩みに直接回答する内容となっています。
導入前の準備: Grafana環境とOpenTelemetryの要件確認
Grafana v10.xでのOpenTelemetryプラグイン導入は、事前準備が不可欠です。特に現在のバージョンでは、互換性のある環境構築が必須です。
Grafana v10.xの互換性チェック
| 評価項目 | 必須条件 | 備考 |
|---|---|---|
| Grafanaバージョン | 10.0以上 | v9.xでは公式プラグイン非対応 |
| OpenTelemetry Collectorバージョン | 1.26.0以上 | v1.25未満はデータ同期エラー発生 |
| OS要件 | Linux/Windows/macOS | Docker環境もサポート |
注意: 非公式リソース（例:GitHubフォーク）を使用すると、セキュリティ更新が遅れる可能性があります。必ず公式ドキュメントで最新情報を確認してください。
公式リポジトリからのプラグイン取得方法
- Grafanaの管理画面から 「Configuration > Plugins」 を開く
- 検索バーに
OpenTelemetryと入力し、公式リポジトリ配下のプラグインを選択 - 「Install」をクリック後、Grafanaが自動で依存ライブラリをダウンロード
重要: 非公式プラグインはサポート対象外です。公式マーケットプレイスで検索することを推奨します。
プラグインの有効化手順
Grafana v10.xでは、プラグインのロードフローに新たなセキュリティ設定が導入されています。特にロードバランサー環境での配備には注意が必要です。
UI経由でのプラグイン検索・インストール
- Grafana管理画面から 「Plugins」タブ を選択
- 検索バーに
OpenTelemetryと入力し、表示された公式プラグインをクリック - 「Install」ボタンを押し、Grafana v10.xの新API仕様に対応するバージョンを選択
ロードバランサー環境での静的ファイル配備チェック
- Static files directory:
/var/lib/grafana/plugins/ - セキュリティ設定で静的ファイル配備を許可していない場合、以下のエラーが発生
ERROR: Failed to load plugin static assets
対応策: NginxまたはHAProxyの設定に以下を追加
|
1 2 3 4 |
location ~ ^/(?:static|public)/ { proxy_pass http://localhost:3000; } |
OTelトラースキーマの指定方法
OpenTelemetryデータの可視化には、otel_tracesスキーマの正しく定義が不可欠です。現在のバージョンではGrafana v10.2以降で自動検出機能が強化されています。
otel_tracesスキーマのプロパティ定義例
| プロパティ | 型 | 必須フラグ | 説明 |
|---|---|---|---|
trace_id |
string(32) | ✅ | トレースの一意識別子 |
span_id |
string(16) | ✅ | スパンの一意識別子 |
parent_span_id |
string(16) | ⚠️ | 親スパンIDが存在しない場合null許容 |
name |
string | ✅ | トレースの名前（例: "GET /api/v1/data"） |
複数データソースのスキーマ整合性保証
- 同一時間軸のメトリクスを比較する際は、
__name__ラベルに一貫した命名ルールを適用 - PrometheusとOpenTelemetry Collectorの出力形式が一致しない場合、以下のエラー発生
ERROR: Schema mismatch between data sources
解決策: OpenTelemetry Collectorの設定ファイルで
exporter.prometheusセクションに以下を追加
|
1 2 3 4 5 |
metric_relabel_configs: - source_labels: [__name__] regex: ^otel_(.+) target_label: $1 |
Prometheus連携時のServiceMonitor設定ポイント
OpenTelemetry CollectorとPrometheusの連携では、メトリクスラベルの正規化がカギです。現在のバージョンで推奨されるscrape_interval設定を解説します。
メトリクスラベルの正規化ルール
- 重複ラベルは
__name__に統合（例:otel_http_requests_total -> http_requests_total） - タイムゾーン一貫性:
tz="Asia/Tokyo"をServiceMonitor設定ファイルで明示的に指定
OpenTelemetry CollectorとGrafanaの時系列データ同期方法
- OpenTelemetry CollectorのPrometheusエクスポーターを有効化
- ServiceMonitorに以下を記述（YAML例）:
|
1 2 3 4 5 6 |
spec: endpoints: - port: metrics interval: 30s path: /metrics |
最適値:
intervalは15~60秒が推奨。短すぎるとCPUリソースを浪費、長すぎるとタイムラグが発生
トレーサビリティダッシュボード構築例
Grafana v10.xでは、Trace ID自動補完やSpanツリーの階層表示が強化されています。以下は典型的な可視化テンプレートです。
サービスメトリクスの可視化テンプレート
- グラフタイプ: 面積チャート（例: トレース数/時間）
- フィルター条件:
service.name = "user-service"で絞り込み - Spanツリー表示:
grafana
from(bucket: "otel-traces")
|> range(start: -1h)
|> filter(fn: (r) => r._measurement == "trace" and r.service_name == "api-gateway")
|> group(columns: ["service_name"])
|> aggregateWindow(every: 30s, fn: sum)
トレース検索UIのカスタムフィルタ設定
- Trace ID自動補完: テキストボックスに
T-と入力すると、過去1週間のトレースIDを候補として表示 - Spanツリー階層表示:
json
{
"expand": true,
"maxDepth": 5
}
Grafana v10.x対応設定
v10.5以降ではセキュリティポリシーとYAML構文が変更されました。以下は主要な更新点です。
プラグインコンフィギュレーションファイルのYAML構文変更点
| 旧バージョン | 新バージョン（v10.5以降） |
|---|---|
plugin.config → otel.traces.config |
- |
otel_traces_schema: "v0.8" |
schema_version: "latest" |
OAuth認証時のセキュリティポリシー強化
- プロキシ設定: 新しいセキュアなプロキシモジュールを有効化
yaml
auth:
proxy:
enabled: true
header_name: X-Forwarded-User
pass_through_headers:
- X-Forwarded-For
注意: ロギングレベルは
info以上で設定し、デバッグモードではセキュリティリスクが高まるため避けること
トラブルシューティングとよくある問題
トレースデータが表示されないケースや通信エラーの対処法を解説します。
トレースデータ非表示時の確認手順
- Grafanaコンソールで
/api/datasources/otel-tracesにアクセス - HTTPステータスコード確認:
403 Forbiddenの場合は認証設定を再確認 - OpenTelemetry Collectorログ:
bash
journalctl -u otel-collector --since "1 hour ago" | grep -i error
コレクターサービスとの通信エラーコード一覧
| エラーコード | 説明 | 対処法 |
|---|---|---|
503 Service Unavailable |
トレースデータの送信が滞っている | OpenTelemetry Collectorのバッファサイズを拡張 |
415 Unsupported Media Type |
データ形式不一致（例: Protobuf vs JSON） | exporter.otlp設定ファイルにprefer_json = true追加 |
診断コマンド: Grafana CLIで実行
|
1 2 |
grafana-cli plugins diag otel-traces |
- プラグイン有効化の手順を守る
- スキーマ整合性を常に確認する
- Prometheusとの同期に注意深く設定を検証する
- v10.x特有のセキュリティ設定を忘れずに適用する
最新情報をもとにしたこのガイドで、OpenTelemetryとGrafanaの連携がスムーズに行えるようになります。公式ドキュメントの確認は、導入後のトラブル回避に不可欠です。