概要
Grafana Loki は、ラベルを使用してログ ストリームを検索し、LogQL を使用してログの内容をクエリするログ集約システムです。従来の全文検索ログ プラットフォームのように、ログの各行のすべての単語に大量のインデックスを付けることはありません。 2026 年に Docker Compose を使用して Loki テスト環境をセットアップする場合、2 つの点を見落とす可能性が最も高くなります。Promtail は LTS/EOL 段階に入り、新しい収集方向では Grafana Alloy を優先する必要があります。ラベル設計でカーディナリティが制御されていない場合、クエリとコストの問題がすぐに発生します。
この記事の日本語版では、小規模な Docker Compose テスト スタック、Loki/Grafana/収集エージェントの構造、Alloy の移行方向、ラベルとストレージの判断、初めてビルドするときによく行き詰まる障害ケースなど、元の韓国語テキストの範囲が維持されています。
この記事の内容
この記事の内容
背景
初めて Loki に触れるとき、多くの人は、Loki をログ テキストに完全なインデックスを付ける Elasticsearch のようなシステムだと考えます。しかし、Loki の核となるアイデアは異なります。 job、service_name、namespace、container このタイプのラベルはログ ストリームを特定し、LogQL を使用してログ ストリーム内でフィルタリングします。
このアプローチでは、インデックス作成と保管のコストを削減できますが、ラベルの選択が運用と保守の問題に直接なります。バンドル request_id、user_id、trace_id すべてのリクエストを変更するこの種の値をラベルに入れると、カーディナリティが高くなりやすく、クエリが遅くなったり、コストが増加したりする可能性があります。
もう 1 つの重要な変更は Promtail です。 Grafana のドキュメントには、Promtail が長期サポート段階に入り、2026 年 3 月 2 日に EOL になると記載されています。既存の Promtail の例はレガシー環境を理解するために引き続き使用できますが、新しいシステム設計ではまず Grafana Alloy を検討する必要があります。
Loki アーキテクチャを理解する方法
基本的な Loki ログ収集スタックは、通常 3 つの部分に分かれています。
| コンポーネント | 効果 |
|---|---|
| Loki | ログを保存し、LogQL クエリを処理します。 |
| Grafana Alloy またはその他のログ収集エージェント | ファイル、コンテナログ、または Kubernetes ログを読み取り、Loki に送信します。 |
| Grafana | ログの検索、ダッシュボードの作成、アラートの構成のためのデータソースとして Loki を接続します。 |
小規模なローカル テストの場合は、単一の Loki コンテナーで十分です。運用環境では、ストレージ、レプリケーション、保存期間、クエリ パフォーマンス、マルチテナンシー、アラーム、障害回復をさらに設計する必要があります。
Docker Compose テスト構成
Grafana の Loki ドキュメントでは、Docker と Docker Compose を評価、テスト、開発の目的に位置付けています。運用環境では、ローカル Compose ファイルを正式な運用およびメンテナンス ソリューションとして直接使用するのではなく、Helm や Tanka などのデプロイメント方法を検討する必要があります。
最小限のテスト スタックは次のように開始できます。
services:
loki:
image: grafana/loki:3.7.0
ports:
- "3100:3100"
command: -config.file=/etc/loki/local-config.yaml
grafana:
image: grafana/grafana:latest
ports:
- "3000:3000"
environment:
- GF_SECURITY_ADMIN_USER=admin
- GF_SECURITY_ADMIN_PASSWORD=****
depends_on:
- lokiサービスを開始します。
docker compose up -dホスト マシンから Loki の準備ができているかどうかを確認します。
curl http://localhost:3100/readyLokiが正常ならアプローチが見えるはず ready 応答。 Grafana はブラウザで開くことができます。
http://localhost:3000これは単なる学習用の構成です。単一のコンテナーとローカル ファイル システム ストレージを直接長期ログ プラットフォームとして扱わないでください。
今 Alloy を見る理由
古い Loki チュートリアルの多くは Promtail を使用しています。これが、検索結果が依然として Promtail フラグメントでいっぱいである理由ですが、これは新しいスタックを作成するための最も安全な出発点ではなくなりました。
Promtail EOL：2026-03-02
新的采集方向：Grafana AlloyPromtail が既存の環境ですでに使用されている場合でも、システムがすぐに失敗するわけではありません。これが実際に意味することは、ロギング アーキテクチャを作成またはリファクタリングするときに、Alloy 移行計画を設計に組み込む必要があるということです。 Grafana は、移行ツールと Alloy コレクション ドキュメントも提供します。運用環境に切り替える前に、変換された構成をテスト環境で検証する必要があります。
新项目：优先查看 Alloy
既存の Promtail：移行計画を立て、テストする
短期のローカル検証：旧例は参照可。ただし Promtail が LTS/EOL 段階であることを明記するラベル設計とストレージの考慮点
ラベルは、Loki クエリのエントリ ポイントです。ログ ソースを記述するのに適しており、可能な限りカーディナリティの低い値を使用する必要があります。
適切なラベルの例:
service_name="api-server"
environment="prod"
namespace="backend"
container="nginx"次の値は頻繁に変更されるため、ラベルとしては適していません。
request_id="a1b2c3..."
user_id="123456"
ip="203.0.113.10"
trace_id="..."カーディナリティの高いフィールドを頻繁に検索する必要がある場合は、それを直接ラベルに変換するのではなく、構造化メタデータまたはログ本文のフィルタリングを検討してください。
ストレージも同様に重要です。テスト用のローカル ファイル システムは問題ありませんが、運用環境では、S3、GCS、Azure Blob、保持ポリシーなどのオブジェクト ストレージを評価する必要があります。保存期間が設定されていない場合、ログは増大し続け、最終的にはディスク使用量やオブジェクト ストレージの費用の問題になります。
トラブル事例と解決策
ケース 1: Grafana が Loki データソースに接続できない
よくある間違いは Grafana に記入することです http://localhost:3100, ただし、Grafana 自体は Docker Compose コンテナーで実行されます。 Grafana コンテナの場合、localhost Loki コンテナではなく、Grafana コンテナ自体を指します。
Compose サービス間でアクセスする場合は、サービス名を使用する必要があります。
http://loki:3100ホスト マシンから直接確認する場合、次のコマンドは引き続き機能します。
curl http://localhost:3100/readyホスト チェックは正常だが、Grafana データソースが失敗する場合は、まずデータソース アドレスを次のように書き込む必要があるかどうかを確認します。 http://loki:3100。
ケース 2: Loki は正常ですが、ログが表示されません
Loki の起動が成功しても、コレクターがログを送信したことを意味するわけではありません。まずサーバーのステータスを確認します。
curl http://localhost:3100/readyコレクターと Compose ログを再度確認します。
docker compose logs急いで再インストールせずに、まず次の点を確認してください。
Loki push URL 是否正确？
Docker 网络和服务名是否正确？
日志文件路径在采集器容器内是否可见？
ラベル設定でログが別の stream に送られていないか？ケース 3: ラベル値が多すぎるとクエリが遅くなる
これは、Loki の運用と保守において非常に一般的な問題です。pod、container、namespace このようなラベルは適切かもしれませんが、リクエストレベルの値では作成されるストリームが多すぎます。
まず、ラベル コレクションと狭い範囲のクエリを確認します。
{service_name="api-server"}運用環境では、次の単純なルールを使用できます。
ラベルには低カーディナリティの値だけを入れる
ユーザー ID、リクエスト ID、セッション ID をラベルにしない
频繁变化的值放在 structured metadata 或日志内容中处理ケース 4: Promtail チュートリアルは機能するが、デザインが古い
検索結果にはまだ Promtail の例がたくさんあります。新しい環境を直接コピーしないでください。最初に Alloy のドキュメントを読んでください。
备份现有 Promtail 配置
阅读 Alloy 迁移说明
変換後の設定をテスト環境で検証する
本番切り替え前にログ欠落がないか確認するケース 5: 保持ポリシーが設定されておらず、ストレージが増加し続ける
ローカルテストでは明らかではないため、本番環境ではトラブルが発生しやすいです。アクセス ログとデバッグ ログは、予想よりも早く増加する可能性があります。
保留周期
削除ポリシー
ストレージ種別
压缩/ chunk 设置
不同环境的日志级别ケース 6: Docker Compose テスト ファイルを本番環境に直接使用する
Docker Compose は、評価と開発の両方に適しています。運用環境は、リカバリ、ストレージ、スケーリング、セキュリティ、認証、監視のために個別に設計する必要があります。
基于 Helm 的 Kubernetes 部署
オブジェクトストレージ連携
retention 配置
Grafana 认证与权限
Loki 自身监控
备份与灾难恢复计划ベストプラクティス
- 学習と検証のフェーズは、Docker Compose を使用した小さなステップから始まります。
- 新しいコレクションのリンクについては、まず Grafana Alloy を見て、次に古い Promtail クリップを見てください。
- 最初はラベルを少なくしてから、ラベルを追加してください。クエリを改善できる場合にのみラベルを追加してください。
- ラベルに高いカーディナリティ値を入れないでください。
- 製造前に保管と保持を設計します。
- ダッシュボードを磨き上げる前に、ログの損失、ストレージ コスト、クエリのパフォーマンスを確認してください。
よくある間違い
Loki を Elasticsearch のように考える
Loki は、ログのすべての行のすべての単語にインデックスを付けるわけではありません。ラベルのデザインはクエリの動作とコストに直接影響します。
Promtail の例が現在推奨されているパスであると誤って考えている
Promtail の例は数多くありますが、Promtail はすでに LTS/EOL ステータスにあります。新しいシステムでは合金の評価を優先する必要があります。
容器内で使い続ける localhost
Docker Compose 内では、localhost 現在のコンテナ自体です。 Grafana には通常、次のものが必要です http://loki:3100。
ログを保持せずに継続的に収集する
ログは今後も増えていきます。保持ポリシーと削除ポリシーがなければ、ディスク フットプリントやオブジェクト ストレージの料金は遅かれ早かれ事故につながるでしょう。
結論
Grafana Loki は比較的コストに優しいログ システムを構築できますが、実際に難しいのは最初の Docker コマンドではなく、ラベルの設計、収集エージェントの選択、ストレージ、保持、およびクエリ モードです。
2026 年に新しい環境を構築する場合は、現在の Loki 3.7.x 系ドキュメントを参照し、Promtail の例をレガシー/LTS マテリアルとして扱い、Grafana Alloy を中心に計画する必要があります。 Docker Compose は学習には適していますが、運用環境では、Helm またはその他の運用および保守プロセス、オブジェクト ストレージ、保持、監視、回復の追加設計が必要です。
参考文献
- Grafana Loki GitHub Release v3.7.2
- Grafana Loki Docker インストール ドキュメント
- Grafana Loki Promtail ドキュメント
- Grafana Loki 合金のドキュメント
- Grafana Loki ラベルのドキュメント
- Grafana Loki 保管文書
- Grafana Loki クエリのドキュメント