loki-config-generator

Loki 設定ジェネレーター

概要

ベストプラクティスに基づいて、本番環境に対応した Grafana Loki サーバー設定を生成します。モノリシック、シンプルスケーラブル、マイクロサービスの各デプロイモードに対応し、S3、GCS、Azure、またはファイルシステムのストレージを利用できます。

現在の安定版： Loki 3.6.2（2025 年 11 月） 重要： Promtail は 3.4 で非推奨になりました。代わりに Grafana Alloy を使用してください。Alloy のパイプラインについては examples/grafana-alloy.alloy、Kubernetes へのデプロイについては examples/grafana-alloy-daemonset.yaml を参照してください。

使用するタイミング

Loki のデプロイ、ゼロからの設定作成、Loki への移行、マルチテナントロギングの実装、ストレージバックエンドの設定、または既存のデプロイの最適化を行う場合に呼び出してください。

---

生成方法

方法 1：スクリプトによる生成（推奨）

一貫性があり、検証済みの設定を生成するには scripts/generate_config.py を使用してください。

# Simple Scalable with S3 (production)
python3 scripts/generate_config.py \
  --mode simple-scalable \
  --storage s3 \
  --bucket my-loki-bucket \
  --region us-east-1 \
  --retention-days 30 \
  --otlp-enabled \
  --output loki-config.yaml

# Monolithic with filesystem (development)
python3 scripts/generate_config.py \
  --mode monolithic \
  --storage filesystem \
  --no-auth-enabled \
  --output loki-dev.yaml

# Production with Thanos storage (Loki 3.4+)
python3 scripts/generate_config.py \
  --mode simple-scalable \
  --storage s3 \
  --thanos-storage \
  --otlp-enabled \
  --time-sharding \
  --output loki-thanos.yaml

スクリプトのオプション：

オプション	説明
--mode	monolithic、simple-scalable、microservices
--storage	filesystem、s3、gcs、azure
--auth-enabled / --no-auth-enabled	認証を明示的に有効化／無効化
--otlp-enabled	OTLP 取り込み設定を有効化
--thanos-storage	Thanos オブジェクトストレージクライアントを使用（3.4 以降、クラウドバックエンド）
--time-sharding	順序が前後したデータの取り込みを有効化（simple-scalable）
--ruler	アラート／記録ルールを有効化（monolithic 以外）
--horizontal-compactor	main／worker モード（simple-scalable、3.6 以降）
--zone-awareness	マルチ AZ 配置の保護機能を有効化
--limits-dry-run	上限超過による拒否を適用せずにログに記録

方法 2：手動設定

スクリプトによる生成では特定の要件を満たせない場合や、設定構造を学ぶ場合は、以下の段階的なワークフローに従ってください。

出力形式

Kubernetes にデプロイする場合は、次の両方の形式を生成してください。

1. Loki ネイティブ設定（loki-config.yaml）- ConfigMap または直接利用するためのもの
2. Helm の値（values.yaml）- Helm チャートでデプロイするためのもの

Helm 形式については examples/kubernetes-helm-values.yaml を参照してください。

---

ドキュメントの参照

Context7／ウェブ検索を使用するタイミング

必須 — 次の内容には Context7 MCP を使用してください。

• Loki 3.4 以降の機能（Thanos ストレージ、時間シャーディング）の設定
• Loki 3.6 以降の機能（水平コンパクター、強制ラベル）の設定
• Bloom フィルターの設定（複雑で実験的）
• 標準的なパターンを超えるカスタム OTLP 属性マッピング
• 設定エラーのトラブルシューティング

任意 — 次の内容ではドキュメントの参照を省略できます。

• 標準的なデプロイモード（monolithic、simple-scalable）
• 基本的なストレージ設定（S3、GCS、Azure、filesystem）
• デフォルトの上限とコンポーネント設定
• references/ ディレクトリに記載されている設定

Context7 MCP（推奨）

resolve-library-id: "grafana loki"
get-library-docs: /websites/grafana_loki, topic: [component]

トピックの例： storage_config、limits_config、otlp、compactor、ruler、bloom

ウェブ検索の代替手段

Context7 が利用できない場合に使用してください："Grafana Loki 3.6 [component] configuration documentation site:grafana.com"

---

設定ワークフロー

段階 1：要件の確認

デプロイモード：

モード	規模	用途
モノリシック	<100GB/日	テスト、開発
シンプルスケーラブル	100GB-1TB/日	本番環境
マイクロサービス	>1TB/日	大規模、マルチテナント

ストレージバックエンド： S3、GCS、Azure Blob、ファイルシステム、MinIO

主な質問： 予想されるログ量はどれくらいですか？保持期間はどれくらいですか？マルチテナントが必要ですか？高可用性の要件はありますか？Kubernetes にデプロイしますか？

必要な情報が不足している場合は、ユーザーに直接質問してください。

段階 2：スキーマの設定（重要）

すべての新規デプロイ（Loki 2.9 以降）では、TSDB と v13 スキーマを使用してください。

schema_config:
  configs:
    - from: "2025-01-01"  # Use deployment date
      store: tsdb
      object_store: s3     # s3, gcs, azure, filesystem
      schema: v13
      index:
        prefix: loki_index_
        period: 24h

重要： デプロイ後にスキーマを変更するには、移行が必要です。

ステージ 3：ストレージの設定

S3：

common:
  storage:
    s3:
      s3: s3://us-east-1/loki-bucket
      s3forcepathstyle: false

GCS： gcs: { bucket_name: loki-bucket } Azure： azure: { container_name: loki-container, account_name: ${AZURE_ACCOUNT_NAME} } ファイルシステム： filesystem: { chunks_directory: /loki/chunks, rules_directory: /loki/rules }

ステージ 4：コンポーネントの設定

Ingester：

ingester:
  chunk_encoding: snappy
  chunk_idle_period: 30m
  max_chunk_age: 2h
  chunk_target_size: 1572864  # 1.5MB
  lifecycler:
    ring:
      replication_factor: 3  # 3 for production

Querier：

querier:
  max_concurrent: 4
  query_timeout: 1m

Compactor：

compactor:
  working_directory: /loki/compactor
  compaction_interval: 10m
  retention_enabled: true
  retention_delete_delay: 2h

ステージ 5：制限の設定

limits_config:
  ingestion_rate_mb: 10
  ingestion_burst_size_mb: 20
  max_streams_per_user: 10000
  max_entries_limit_per_query: 5000
  max_query_length: 721h
  retention_period: 30d
  allow_structured_metadata: true
  volume_enabled: true

ステージ 6：サーバーと認証

server:
  http_listen_port: 3100
  grpc_listen_port: 9096
  log_level: info

auth_enabled: true  # false for single-tenant

ステージ 7：OTLP 取り込み（Loki 3.0+）

ネイティブの OpenTelemetry 取り込みには、otlphttp エクスポーターを使用してください（非推奨の lokiexporter は使用しないでください）。

limits_config:
  allow_structured_metadata: true
  otlp_config:
    resource_attributes:
      attributes_config:
        - action: index_label  # Low-cardinality only!
          attributes: [service.name, service.namespace, deployment.environment]
        - action: structured_metadata  # High-cardinality
          attributes: [k8s.pod.name, service.instance.id]

アクション： index_label（検索可能、カーディナリティが低い）、structured_metadata（クエリ可能）、drop

⚠️ k8s.pod.name を index_label として使用しないでください — 代わりに structured_metadata を使用してください。

OTel Collector：

exporters:
  otlphttp:
    endpoint: http://loki:3100/otlp

ステージ 8：キャッシュ

chunk_store_config:
  chunk_cache_config:
    memcached_client:
      host: memcached-chunks
      timeout: 500ms

query_range:
  cache_results: true
  results_cache:
    cache:
      memcached_client:
        host: memcached-results

ステージ 9：高度な機能

Pattern Ingester（3.0+）：

pattern_ingester:
  enabled: true

Bloom フィルター（実験的、3.3+）： 月間 75 TB を超えるデプロイメントでのみ使用してください。structured metadata のみに対応しています。設定については examples/ を参照してください。

時間シャーディング（3.4+）： 順不同の取り込みに使用します。

limits_config:
  shard_streams:
    time_sharding_enabled: true

Thanos Storage（3.4+）： 新しいストレージクライアントです。現在はオプトインで、将来デフォルトになります。

storage_config:
  use_thanos_objstore: true
  object_store:
    s3:
      bucket_name: my-bucket
      endpoint: s3.us-west-2.amazonaws.com

ステージ 10：Ruler（アラート）

ruler:
  storage:
    type: s3
    s3: { bucket_name: loki-ruler }
  alertmanager_url: http://alertmanager:9093
  enable_api: true
  enable_sharding: true

ステージ 11：Loki 3.6 の機能

• 水平スケーラブルな Compactor： horizontal_scaling_mode: main|worker
• ポリシーベースの強制ラベル： enforced_labels: [service.name]
• FluentBit v4： structured_metadata パラメーターに対応

ステージ 12：設定の検証（必須）

デプロイ前に必ず検証してください。

# Syntax and parameter validation
loki -config.file=loki-config.yaml -verify-config

# Print resolved configuration (shows defaults)
loki -config.file=loki-config.yaml -print-config-stderr 2>&1 | head -100

# Dry-run with Docker (if Loki not installed locally)
docker run --rm -v $(pwd)/loki-config.yaml:/etc/loki/config.yaml \
  grafana/loki:3.6.2 -config.file=/etc/loki/config.yaml -verify-config

検証チェックリスト：

• -verify-config による構文エラーがない
• スキーマで tsdb と v13 を使用している
• 本番環境で replication_factor: 3 を設定している
• マルチテナントの場合、auth_enabled: true を設定している
• ストレージの認証情報／IAM が設定されている
• 保持期間が要件を満たしている

---

本番環境のチェックリスト

高可用性の要件

ゾーン認識レプリケーション（本番環境のマルチ AZ デプロイメントでは重要）：

replication_factor: 3 を使用する場合、マルチ AZ デプロイメントでは必ずゾーン認識を有効にしてください。

ingester:
  lifecycler:
    ring:
      replication_factor: 3
      zone_awareness_enabled: true  # CRITICAL for multi-AZ

# Set zone via environment variable or config
# Each pod should set its zone based on node topology
common:
  instance_availability_zone: ${AVAILABILITY_ZONE}

理由： ゾーン認識がないと、3 つのレプリカすべてが同じ AZ に配置される可能性があります。その AZ に障害が発生すると、データが失われます。

Kubernetes での実装：

# In Helm values or pod spec
env:
  - name: AVAILABILITY_ZONE
    valueFrom:
      fieldRef:
        fieldPath: metadata.labels['topology.kubernetes.io/zone']

TLS の設定（本番環境では必須）

すべてのコンポーネント間およびクライアントとの通信で TLS を有効にしてください。

server:
  http_tls_config:
    cert_file: /etc/loki/tls/tls.crt
    key_file: /etc/loki/tls/tls.key
    client_ca_file: /etc/loki/tls/ca.crt  # For mTLS
  grpc_tls_config:
    cert_file: /etc/loki/tls/tls.crt
    key_file: /etc/loki/tls/tls.key
    client_ca_file: /etc/loki/tls/ca.crt

TLS の完全な設定については、examples/production-tls.yaml を参照してください。

本番環境のチェックリスト概要

要件	設定	必須対象
replication_factor: 3	common ブロック	すべての本番環境
zone_awareness_enabled: true	ingester.lifecycler.ring	マルチ AZ
auth_enabled: true	ルートレベル	マルチテナント
TLS を有効化	server ブロック	すべての本番環境
IAM ロール（キーではなく）	ストレージ設定	クラウドストレージ
キャッシュを有効化	chunk_store_config, query_range	パフォーマンス
Pattern ingester	pattern_ingester.enabled	オブザーバビリティ
保持期間を設定	compactor + limits_config	コスト管理

---

モニタリングの推奨事項

監視する主なメトリクス

Prometheus で Loki のメトリクスをスクレイプし、次の重要な指標に対するアラートを設定してください。

# Prometheus scrape config
- job_name: 'loki'
  static_configs:
    - targets: ['loki:3100']

重要なアラート

groups:
  - name: loki-critical
    rules:
      # Ingestion failures
      - alert: LokiIngestionFailures
        expr: sum(rate(loki_distributor_ingester_append_failures_total[5m])) > 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Loki ingestion failures detected"

      # High stream cardinality (performance killer)
      - alert: LokiHighStreamCardinality
        expr: loki_ingester_memory_streams > 100000
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "High stream cardinality - review labels"

      # Compaction not running (retention broken)
      - alert: LokiCompactionStalled
        expr: time() - loki_compactor_last_successful_run_timestamp_seconds > 7200
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Loki compaction stalled - retention not enforced"

      # Query latency
      - alert: LokiSlowQueries
        expr: histogram_quantile(0.99, sum(rate(loki_request_duration_seconds_bucket{route=~"loki_api_v1_query.*"}[5m])) by (le)) > 30
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Loki query P99 latency > 30s"

      # Ingester memory pressure
      - alert: LokiIngesterMemoryHigh
        expr: container_memory_usage_bytes{container="ingester"} / container_spec_memory_limit_bytes{container="ingester"} > 0.8
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Loki ingester memory usage > 80%"

主なメトリクスのリファレンス

メトリクス	説明	対応のしきい値
loki_ingester_memory_streams	メモリ内のアクティブなストリーム数	>100k：カーディナリティを見直す
loki_distributor_ingester_append_failures_total	取り込みの失敗数	>0：直ちに調査する
loki_request_duration_seconds	クエリのレイテンシ	P99 >30s：キャッシュ／querier を追加する
loki_ingester_chunks_flushed_total	チャンクのフラッシュ率	低い場合：ingester の状態を確認する
loki_compactor_last_successful_run_timestamp_seconds	最後のコンパクション	2 時間超：コンパクションが機能していない

Grafana ダッシュボード

Loki の公式ダッシュボードをインポートします：

• ダッシュボード ID：13407 - Loki Logs
• ダッシュボード ID：14055 - Loki Operational

---

Grafana Alloy によるログ収集

Promtail は非推奨です（サポートは 2026 年 2 月に終了します）。新しいデプロイでは Grafana Alloy を使用してください。

Alloy の基本設定

Alloy のパイプラインについては examples/grafana-alloy.alloy を、Kubernetes のデプロイについては examples/grafana-alloy-daemonset.yaml を参照してください。

// Kubernetes log discovery
discovery.kubernetes "pods" {
  role = "pod"
}

// Relabeling for Kubernetes metadata
discovery.relabel "pods" {
  targets = discovery.kubernetes.pods.targets

  rule {
    source_labels = ["__meta_kubernetes_namespace"]
    target_label  = "namespace"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_name"]
    target_label  = "pod"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_container_name"]
    target_label  = "container"
  }
}

// Log collection
loki.source.kubernetes "pods" {
  targets    = discovery.relabel.pods.output
  forward_to = [loki.write.default.receiver]
}

// Send to Loki
loki.write "default" {
  endpoint {
    url = "http://loki-gateway.loki.svc.cluster.local/loki/api/v1/push"

    // For multi-tenant
    tenant_id = "default"
  }
}

Promtail からの移行

# Convert Promtail config to Alloy
alloy convert --source-format=promtail --output=alloy-config.alloy promtail.yaml

---

完全なサンプル

完全な設定については examples/ ディレクトリを参照してください：

• monolithic-filesystem.yaml - 開発／テスト用
• simple-scalable-s3.yaml - S3 を使用する本番環境用
• microservices-s3.yaml - 大規模な分散環境用
• multi-tenant.yaml - テナントごとの制限を設定したマルチテナント環境用
• production-tls.yaml - TLS を有効にした本番環境用の設定
• grafana-alloy.alloy - Alloy によるログ収集パイプライン
• grafana-alloy-daemonset.yaml - Alloy 用 Kubernetes DaemonSet
• kubernetes-helm-values.yaml - Helm チャートの値

最小構成のモノリシック構成：

auth_enabled: false
server:
  http_listen_port: 3100

common:
  path_prefix: /loki
  storage:
    filesystem:
      chunks_directory: /loki/chunks
      rules_directory: /loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory

schema_config:
  configs:
    - from: 2025-01-01
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: loki_index_
        period: 24h

limits_config:
  retention_period: 30d
  allow_structured_metadata: true

compactor:
  working_directory: /loki/compactor
  retention_enabled: true

---

Helm によるデプロイ

helm repo add grafana https://grafana.github.io/helm-charts
helm install loki grafana/loki -f values.yaml

Kubernetes のデプロイ用に、ネイティブ設定と Helm の値を両方生成します。

# values.yaml
deploymentMode: SimpleScalable

loki:
  schemaConfig:
    configs:
      - from: "2025-01-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  limits_config:
    retention_period: 30d
    allow_structured_metadata: true
  # Zone awareness for HA
  ingester:
    lifecycler:
      ring:
        zone_awareness_enabled: true

backend:
  replicas: 3
  # Spread across zones
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
read:
  replicas: 3
write:
  replicas: 3

---

ベストプラクティス

パフォーマンス：

• chunk_encoding: snappy、chunk_target_size: 1572864
• キャッシュを有効にします（チャンク、結果）
• parallelise_shardable_queries: true

セキュリティ：

• リバースプロキシ認証とともに auth_enabled: true を設定します
• クラウドストレージには IAM ロールを使用します（キーをハードコードしないでください）
• すべての通信で TLS を使用します（「本番環境チェックリスト」を参照）

信頼性：

• 本番環境では replication_factor: 3 を設定します
• マルチ AZ 環境では zone_awareness_enabled: true を設定します（「本番環境チェックリスト」を参照）
• インジェスター用に永続ボリュームを使用します
• 取り込み率とクエリのレイテンシを監視します（「モニタリング」セクションを参照）

制限： 過負荷を防ぐため、ingestion_rate_mb と max_streams_per_user を設定します

---

よくある問題

問題	解決方法
インジェスターのメモリ使用量が多い	max_streams_per_user を減らし、chunk_idle_period を短くします
クエリが遅い	max_concurrent を増やし、並列化を有効にして、キャッシュを追加します
取り込みに失敗する	ingestion_rate_mb を確認し、ストレージへの接続を確認します
ストレージの増加が速い	保持期間を有効にし、圧縮を確認して、カーディナリティを見直します
AZ の障害でデータが失われる	zone_awareness_enabled: true を有効にします
設定の検証に失敗する	loki -verify-config を実行し、YAML の構文を確認します

---

非推奨（移行してください）

• boltdb-shipper → tsdb
• lokiexporter → otlphttp
• Promtail → Grafana Alloy（サポートは 2026 年 2 月に終了します）

---

リソース

scripts/generate_config.py - プログラムで設定を生成します（推奨） examples/ - すべてのモードに対応した完全な設定例 references/ - 全パラメーターのリファレンスとベストプラクティス

関連スキル

• logql-generator - LogQL クエリの生成
• fluentbit-generator - Loki へのログ収集