Submit
All skills
Skillintermediate

Loki Configuration Reference

This document provides a comprehensive reference for Grafana Loki configuration parameters.

Claude Code Knowledge Pack7/10/2026

Overview

Loki Configuration Reference

This document provides a comprehensive reference for Grafana Loki configuration parameters.

Current Stable Release: Loki 3.6.2 (November 2025)

Table of Contents

Server Configuration

The server block configures the HTTP and gRPC server settings.

server:
  # HTTP server listen address
  # CLI flag: -server.http-listen-address
  [http_listen_address: <string> | default = ""]

  # HTTP server listen port
  # CLI flag: -server.http-listen-port
  [http_listen_port: <int> | default = 3100]

  # gRPC server listen address
  # CLI flag: -server.grpc-listen-address
  [grpc_listen_address: <string> | default = ""]

  # gRPC server listen port
  # CLI flag: -server.grpc-listen-port
  [grpc_listen_port: <int> | default = 9095]

  # Log level: debug, info, warn, error
  # CLI flag: -log.level
  [log_level: <string> | default = "info"]

  # Log format: logfmt, json
  # CLI flag: -log.format
  [log_format: <string> | default = "logfmt"]

  # Timeout for graceful shutdown
  # CLI flag: -server.graceful-shutdown-timeout
  [graceful_shutdown_timeout: <duration> | default = 30s]

  # HTTP server read timeout
  # CLI flag: -server.http-read-timeout
  [http_server_read_timeout: <duration> | default = 30s]

  # HTTP server write timeout
  # CLI flag: -server.http-write-timeout
  [http_server_write_timeout: <duration> | default = 30s]

  # HTTP server idle timeout
  # CLI flag: -server.http-idle-timeout
  [http_server_idle_timeout: <duration> | default = 120s]

  # Maximum number of simultaneous gRPC connections
  # CLI flag: -server.grpc-max-concurrent-streams
  [grpc_server_max_concurrent_streams: <int> | default = 100]

  # TLS configuration for HTTP server
  http_tls_config:
    [cert_file: <string>]
    [key_file: <string>]
    [client_ca_file: <string>]

  # TLS configuration for gRPC server
  grpc_tls_config:
    [cert_file: <string>]
    [key_file: <string>]
    [client_ca_file: <string>]

Common Configuration

The common block configures shared settings across components.

common:
  # Path prefix for data storage
  [path_prefix: <string> | default = ""]

  # Instance address for ring registration
  [instance_addr: <string>]

  # Replication factor for data durability
  # CLI flag: -common.replication-factor
  [replication_factor: <int> | default = 3]

  # Storage configuration
  storage:
    # S3 storage configuration
    s3:
      [s3: <string>]  # s3://region/bucket format
      [s3forcepathstyle: <boolean> | default = false]
      [access_key_id: <string>]
      [secret_access_key: <string>]
      [endpoint: <string>]
      [region: <string>]
      [insecure: <boolean> | default = false]

    # GCS storage configuration
    gcs:
      [bucket_name: <string>]
      [service_account: <string>]
      [chunk_buffer_size: <int>]

    # Azure storage configuration
    azure:
      [container_name: <string>]
      [account_name: <string>]
      [account_key: <string>]
      [use_managed_identity: <boolean> | default = false]
      [user_assigned_id: <string>]

    # Filesystem storage configuration
    filesystem:
      [chunks_directory: <string>]
      [rules_directory: <string>]

  # Ring configuration for service discovery
  ring:
    kvstore:
      # Store type: consul, etcd, memberlist, inmemory
      [store: <string> | default = "memberlist"]
      [prefix: <string> | default = "collectors/"]

      # Consul configuration
      consul:
        [host: <string> | default = "localhost:8500"]
        [acl_token: <string>]

      # Etcd configuration
      etcd:
        [endpoints: <list of strings>]
        [username: <string>]
        [password: <string>]

Schema Configuration

The schema_config block defines how Loki stores and indexes data. This is critical and cannot be changed after deployment without migration.

schema_config:
  configs:
    # Date when this schema takes effect (YYYY-MM-DD format)
    - from: <daytime>

      # Index store type: tsdb, boltdb-shipper (deprecated)
      # TSDB is recommended for all new deployments
      [store: <string> | default = "tsdb"]

      # Object store type: s3, gcs, azure, filesystem
      [object_store: <string>]

      # Schema version: v13 is latest and recommended
      [schema: <string> | default = "v13"]

      # Index configuration
      index:
        # Table name prefix
        [prefix: <string> | default = "index_"]
        # Table period (24h recommended)
        [period: <duration> | default = 24h]

Best Practice: Always use store: tsdb and schema: v13 for new deployments.

Storage Configuration

Legacy Storage Configuration

storage_config:
  # TSDB shipper configuration
  tsdb_shipper:
    [active_index_directory: <string>]
    [cache_location: <string>]
    [cache_ttl: <duration> | default = 24h]
    index_gateway_client:
      [server_address: <string>]

  # AWS/S3 configuration
  aws:
    [s3: <string>]
    [s3forcepathstyle: <boolean>]
    [access_key_id: <string>]
    [secret_access_key: <string>]

  # GCS configuration
  gcs:
    [bucket_name: <string>]

  # Azure configuration
  azure:
    [container_name: <string>]
    [account_name: <string>]
    [account_key: <string>]

  # Filesystem configuration
  filesystem:
    [directory: <string>]

Thanos Object Storage Client (Loki 3.4+)

The Thanos-based storage client provides consistent configuration across Grafana's databases.

storage_config:
  # Enable Thanos object storage client
  # MUTUALLY EXCLUSIVE with legacy storage config
  use_thanos_objstore: true

  object_store:
    # Storage prefix for all objects (cannot contain dashes)
    [storage_prefix: <string>]

    # S3 configuration
    s3:
      [bucket_name: <string>]
      [endpoint: <string>]
      [region: <string>]
      [access_key_id: <string>]
      [secret_access_key: <string>]
      [native_aws_auth_enabled: <boolean> | default = false]
      [dualstack_enabled: <boolean> | default = false]
      [storage_class: <string> | default = "STANDARD"]
      [max_retries: <int> | default = 10]

      # HTTP client settings
      http:
        [idle_conn_timeout: <duration> | default = 1m30s]
        [response_header_timeout: <duration> | default = 2m]
        [insecure_skip_verify: <boolean> | default = false]

      # Server-side encryption
      sse:
        [type: <string>]  # SSE-KMS or SSE-S3
        [kms_key_id: <string>]
        [kms_encryption_context: <string>]

    # GCS configuration
    gcs:
      [bucket_name: <string>]
      [service_account: <string>]
      [chunk_buffer_size: <int>]
      [max_retries: <int> | default = 5]

    # Azure configuration
    azure:
      [account_name: <string>]
      [account_key: <string>]
      [container_name: <string>]
      [use_managed_identity: <boolean> | default = false]

    # Filesystem configuration
    filesystem:
      [dir: <string>]  # Note: 'dir' not 'directory'

Migration Notes:

  • use_thanos_objstore: true is mutually exclusive with legacy storage config
  • disable_dualstack → dualstack_enabled (inverted logic)
  • signature_version removed (always uses V4)
  • http_config → http (nested block)
  • Storage prefix cannot contain dashes (-) - use underscores

Ingester Configuration

The ingester block configures log ingestion and chunk management.

ingester:
  # Chunk compression algorithm: snappy, gzip, lz4, none
  # CLI flag: -ingester.chunk-encoding
  [chunk_encoding: <string> | default = "snappy"]

  # Flush inactive chunks after this period
  # CLI flag: -ingester.chunk-idle-period
  [chunk_idle_period: <duration> | default = 30m]

  # Keep flushed chunks in memory for this duration
  # CLI flag: -ingester.chunk-retain-period
  [chunk_retain_period: <duration> | default = 15m]

  # Maximum age of a chunk before flushing
  # CLI flag: -ingester.max-chunk-age
  [max_chunk_age: <duration> | default = 2h]

  # Target compressed chunk size (bytes)
  # CLI flag: -ingester.chunk-target-size
  [chunk_target_size: <int> | default = 1572864]  # 1.5MB

  # Number of concurrent chunk flushes
  # CLI flag: -ingester.concurrent-flushes
  [concurrent_flushes: <int> | default = 16]

  # Flush check interval
  # CLI flag: -ingester.flush-check-period
  [flush_check_period: <duration> | default = 30s]

  # WAL (Write-Ahead Log) configuration
  wal:
    [enabled: <boolean> | default = true]
    [dir: <string> | default = "wal"]
    [flush_on_shutdown: <boolean> | default = true]
    [replay_memory_ceiling: <int>]

  # Lifecycler configuration for ring registration
  lifecycler:
    ring:
      kvstore:
        [store: <string>]
      [replication_factor: <int> | default = 3]
    [num_tokens: <int> | default = 128]
    [heartbeat_period: <duration> | default = 5s]
    [join_after: <duration> | default = 0s]
    [observe_period: <duration> | default = 0s]
    [interface_names: <list of strings>]
    [final_sleep: <duration> | default = 30s]

Best Practices:

  • Use chunk_encoding: snappy for best speed/compression balance
  • Target 1.5MB chunks requires 5-10x raw log data
  • Set replication_factor: 3 for production

Distributor Configuration

The distributor block configures log distribution to ingesters.

distributor:
  ring:
    kvstore:
      [store: <string>]
    [heartbeat_timeout: <duration> | default = 1m]

  # OTLP configuration for default resource attributes
  otlp_config:
    # Override default list of resource attributes promoted to index labels
    # Excludes high-cardinality attributes like k8s.pod.name, service.instance.id
    default_resource_attributes_as_index_labels:
      - service.name
      - service.namespace
      - deployment.environment
      - cloud.region
      - cloud.availability_zone
      - k8s.cluster.name
      - k8s.namespace.name
      - k8s.container.name
      - container.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name

  # Ingest limits (Loki 3.5+)
  [ingest_limits_enabled: <boolean> | default = false]
  [ingest_limits_dry_run_enabled: <boolean> | default = false]

Querier Configuration

The querier block configures log query processing.

querier:
  # Maximum concurrent queries per querier
  # CLI flag: -querier.max-concurrent
  [max_concurrent: <int> | default = 4]

  # Query timeout
  # CLI flag: -querier.query-timeout
  [query_timeout: <duration> | default = 1m]

  # Maximum duration for live tailing
  # CLI flag: -querier.tail-max-duration
  [tail_max_duration: <duration> | default = 1h]

  # Extra delay before sending queries to storage
  # CLI flag: -querier.extra-query-delay
  [extra_query_delay: <duration> | default = 0s]

  # Multi-tenant queries (requires auth_enabled: false)
  [multi_tenant_queries_enabled: <boolean> | default = false]

  # Engine configuration
  engine:
    [timeout: <duration> | default = 5m]
    [max_look_back_period: <duration> | default = 30s]

Query Frontend Configuration

The frontend block configures the query frontend.

frontend:
  # Maximum outstanding requests per tenant
  # CLI flag: -querier.max-outstanding-requests-per-tenant
  [max_outstanding_per_tenant: <int> | default = 2048]

  # Compress HTTP responses
  # CLI flag: -querier.compress-http-responses
  [compress_responses: <boolean> | default = true]

  # Response encoding: protobuf (recommended) or json
  [encoding: <string> | default = "protobuf"]

  # Log queries longer than this duration
  # CLI flag: -frontend.log-queries-longer-than
  [log_queries_longer_than: <duration> | default = 0s]

  # Downstream URL for query processing
  [downstream_url: <string>]

Query Range Configuration

The query_range block configures query splitting and caching.

query_range:
  # Align queries with step intervals
  # CLI flag: -querier.align-queries-with-step
  [align_queries_with_step: <boolean> | default = false]

  # Maximum retries for failed queries
  # CLI flag: -querier.max-retries
  [max_retries: <int> | default = 5]

  # Enable parallel execution of shardable queries
  # CLI flag: -querier.parallelise-shardable-queries
  [parallelise_shardable_queries: <boolean> | default = true]

  # Cache query results
  [cache_results: <boolean> | default = false]

  # Results cache configuration
  results_cache:
    cache:
      # Embedded cache
      embedded_cache:
        [enabled: <boolean> | default = false]
        [max_size_mb: <int> | default = 100]
        [ttl: <duration> | default = 1h]

      # Memcached client
      memcached_client:
        [host: <string>]
        [service: <string>]
        [timeout: <duration> | default = 500ms]
        [max_idle_conns: <int> | default = 16]
        [update_interval: <duration> | default = 1m]
        [consistent_hash: <boolean> | default = true]

      # Redis client
      redis:
        [endpoint: <string>]
        [timeout: <duration>]
        [expiration: <duration>]

Compactor Configuration

The compactor block configures index compaction and retention.

compactor:
  # Directory for compaction work
  # CLI flag: -boltdb.shipper.compactor.working-directory
  [working_directory: <string>]

  # How often to run compaction
  # CLI flag: -boltdb.shipper.compactor.compaction-interval
  [compaction_interval: <duration> | default = 10m]

  # Enable retention enforcement
  # CLI flag: -compactor.retention-enabled
  [retention_enabled: <boolean> | default = false]

  # Delay before deleting expired data
  # CLI flag: -compactor.retention-delete-delay
  [retention_delete_delay: <duration> | default = 2h]

  # Number of parallel deletion workers
  # CLI flag: -compactor.retention-delete-worker-count
  [retention_delete_worker_count: <int> | default = 150]

  # Delete request store backend (Loki 3.5+)
  # Options: boltdb, sqlite, s3, gcs, azure
  # SQLite recommended over BoltDB for better query optimization
  [delete_request_store: <string>]

  # Horizontally Scalable Compactor (Loki 3.6+)
  # Modes: disabled (default), main, work