[OpenTelemetry 検証1] local検証環境を立てるまで

はじめに

OpenTelemetry についてさっと検証できる環境が欲しかったため、ローカルで実装してみました。

どのような構成にしたかなど整理しておきたいと思います。

なお勝手な印象ですが、OpenTelemetry を採用しているケースでは k8s でインフラを構成している場合が多い印象なのですが、ローカルの検証目的で利用する場合は少し過剰なので docker-compose で構成させています。

構成や利用したコンテナサービスについて

以下のような構成にしています。

article-server (Go)
  ↓ OTLP (4317)
Grafana Alloy
  ├→ Tempo (Traces)
  ├→ Prometheus (Metrics)
  └→ Loki (Logs)
      ↓
  Grafana (可視化)

詳細は明記しませんが、それぞれ以下のような役割を持ちます。

コンポーネント	役割	振る舞い
article-server	ブログ記事管理 API	HTTP リクエスト処理、トレース/メトリクスを OTLP で Alloy へ送信 (4317)
Grafana Alloy	テレメトリ収集/転送	OTLP 受信 (4317/4318) → Tempo/Prometheus、Docker ログ収集 → Loki
Tempo	分散トレースストレージ	スパン受信/保存、TraceQL クエリ、trace_id で Loki 相関
Prometheus	メトリクス時系列 DB	Remote Write 受信/保存、PromQL クエリ/集計
Loki	ログ集約エンジン	Push API 受信/保存、LogQL クエリ、trace_id で Tempo 相関
Grafana	統合可視化	Traces/Metrics/Logs 可視化、trace_id でログ⇔トレース相関

Grafana Alloy: https://grafana.com/docs/alloy/latest/
Tempo: https://grafana.com/docs/tempo/latest/
Prometheus: https://prometheus.io/docs/
Loki: https://grafana.com/docs/loki/latest/
Grafana: https://grafana.com/docs/grafana/latest/

ディレクトリ構成について

.
├── article_server
│   ├── cmd
│   ├── Dockerfile
│   ├── go.mod
│   ├── go.sum
│   └── internal # 実際のロジックを定義しているところ。spanなどで可視化した時にわかりやすくなるようにある程度レイヤーを区別
├── pkg
│   ├── errors
│   ├── go.mod
│   ├── go.sum
│   └── otel # otel関連の設定を管理するパッケージ (NewProvider などで各種 Provider, Exporterなどを設定してるところ)
├── _data // ホストマシンにマウントしているデータ群 (基本触らない)
│   ├── grafana
│   ├── loki
│   ├── prometheus
│   └── tempo
├── _docker # 各サービスの初期設定などを管理しているディレクトリ (詳細は後述)
│   ├── alloy
│   ├── grafana
│   ├── loki
│   ├── prometheus
│   └── tempo
└── docker-compose.yaml

※補足: docker-compose.yaml の設定

各種コンテナサービスの詳細

_docker 配下は以下のように設定しています。※このあたりも長くなるので詳細は省きます

./_docker
├── alloy
│   └── config.alloy                          # OTLP 受信 (4317/4318)、バッチ処理、Tempo/Prometheus/Loki への転送設定
├── grafana
│   ├── grafana.ini                           # Grafana 基本設定 (ポート、認証、管理者アカウント)
│   ├── provisioning
│   │   ├── dashboards
│   │   │   ├── article-server.json           # Article Server 監視ダッシュボード定義 (Latency/Request Rate)
│   │   │   └── dashboards.yaml               # ダッシュボード JSON ファイルの自動読み込み設定
│   │   └── datasources
│   │       └── datasources.yaml              # データソース (Tempo/Prometheus/Loki) 自動登録、trace_id 相関設定
│   └── setup.sh                              # 組織名などの初期設定スクリプト (起動時に 1 回実行)
├── loki
│   └── loki.yaml                             # ログストレージ設定 (chunk/index スキーマ、保持期間 7 日)
├── prometheus
│   └── prometheus.yml                        # メトリクススクレイプ設定、Remote Write 受信設定
└── tempo
    └── tempo.yaml                            # トレースストレージ設定 (WAL/ブロック、保持期間 7 日)

参考までに今回設定した内容を掲載します

動作確認

コンテナを起動して、各サービスが起動しているかどうか、及びGUIを提供しているサービスについてはブラウザ上でアクセスできるか確認してみます。

❯ docker compose up -d
[+] Running 8/8
 ✔ Network infrastructure_default             Created                                                               0.0s
 ✔ Container infrastructure-prometheus-1      Started                                                               0.4s
 ✔ Container infrastructure-loki-1            Started                                                               0.3s
 ✔ Container infrastructure-tempo-1           Started                                                               0.4s
 ✔ Container infrastructure-alloy-1           Started                                                               0.5s
 ✔ Container infrastructure-grafana-1         Started                                                               0.5s
 ✔ Container infrastructure-grafana-init-1    Started                                                               0.6s
 ✔ Container infrastructure-article-server-1  Started

各サービス起動していることを確認

スクリーンショット 2026-02-16 2.10.56.png