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	启用多可用区放置保护措施
--limits-dry-run	记录限制拒绝情况，但不强制执行

方法 2：手动配置

如果脚本生成无法满足特定需求，或需要了解配置结构，请按照以下分阶段工作流操作。

输出格式

对于 Kubernetes 部署，请生成两种格式：

1. 原生 Loki 配置（loki-config.yaml）——用于 ConfigMap 或直接使用
2. Helm values（values.yaml）——用于 Helm Chart 部署

Helm 格式请参见 examples/kubernetes-helm-values.yaml。

---

文档查询

何时使用 Context7/网页搜索

必须使用 Context7 MCP 的情况：

• 配置 Loki 3.4+ 的功能（Thanos 存储、时间分片）
• 配置 Loki 3.6+ 的功能（水平压缩器、强制标签）
• Bloom 过滤器配置（复杂、实验性）
• 超出标准模式的自定义 OTLP 属性映射
• 排查配置错误

可跳过文档查询的情况：

• 标准部署模式（monolithic、simple-scalable）
• 基本存储配置（S3、GCS、Azure、文件系统）
• 默认限制和组件设置
• 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+），请使用带有 v13 架构的 TSDB：

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 exporter（不要使用已弃用的 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 Filters（实验性，3.3+）： 仅适用于每月 >75TB 的部署。仅对结构化元数据有效。配置请参见 examples/。

时间分片（3.4+）： 用于乱序摄取：

limits_config:
  shard_streams:
    time_sharding_enabled: true

Thanos 存储（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 未报告语法错误
• Schema 使用 tsdb 和 v13
• 生产环境设置 replication_factor: 3
• 多租户环境设置 auth_enabled: true
• 已配置存储凭据/IAM
• 保留期限符合要求

---

生产环境检查清单

高可用性要求

区域感知复制（生产环境多可用区部署的关键要求）：

使用 replication_factor: 3 时，多可用区部署务必启用区域感知：

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 个副本可能会落在同一可用区。如果该可用区发生故障，数据将丢失。

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 block	所有生产环境
zone_awareness_enabled: true	ingester.lifecycler.ring	多可用区
auth_enabled: true	root level	多租户
启用 TLS	server block	所有生产环境
IAM 角色（而非密钥）	storage config	云存储
启用缓存	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	Chunk 刷新速率	速率较低：检查 ingester 健康状态
loki_compactor_last_successful_run_timestamp_seconds	上次压缩时间	超过 2h：压缩功能异常

Grafana 仪表板

导入官方 Loki 仪表板：

• 仪表板 ID：13407 - Loki 日志
• 仪表板 ID：14055 - Loki 运维

---

使用 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 chart 配置值

最简单体配置：

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
• 多可用区环境启用 zone_awareness_enabled: true（参见生产环境检查清单）
• 为 ingester 使用持久卷
• 监控摄取速率和查询延迟（参见监控部分）

**限制：**设置 ingestion_rate_mb、max_streams_per_user 以防止过载

---

常见问题

问题	解决方案
ingester 内存占用过高	降低 max_streams_per_user，缩短 chunk_idle_period
查询缓慢	提高 max_concurrent，启用并行化，添加缓存
摄取失败	检查 ingestion_rate_mb，确认存储连接正常
存储增长过快	启用保留策略，检查压缩，审查基数
可用区故障导致数据丢失	启用 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