Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Configuring Loki
You can use Grafana Cloud to avoid installing, maintaining, and scaling your own instance of Grafana Loki. Create a free account to get started, which includes free forever access to 10k metrics, 50GB logs, 50GB traces, 500VUh k6 testing & more.
Loki is configured in a YAML file (usually referred to as loki.yaml )
which contains information on the Loki server and its individual components,
depending on which mode Loki is launched in.
Configuration examples can be found in the Configuration Examples document.
- Configuring Loki
- Printing Loki Config At Runtime
- Configuration File Reference
- server_config
- distributor_config
- querier_config
- query_frontend_config
- queryrange_config
- ruler_config
- frontend_worker_config
- ingester_client_config
- ingester_config
- consul_config
- etcd_config
- memberlist_config
- storage_config
- chunk_store_config
- cache_config
- schema_config
- limits_config
- table_manager_config
- tracing_config
- Runtime Configuration file
Printing Loki Config At Runtime
If you pass Loki the flag -print-config-stderr or -log-config-reverse-order, (or -print-config-stderr=true)
Loki will dump the entire config object it has created from the built in defaults combined first with
overrides from config file, and second by overrides from flags.
The result is the value for every config object in the Loki config struct, which is very large…
Many values will not be relevant to your install such as storage configs which you are not using and which you did not define, this is expected as every option has a default value if it is being used or not.
This config is what Loki will use to run, it can be invaluable for debugging issues related to configuration and is especially useful in making sure your config files and flags are being read and loaded properly.
-print-config-stderr is nice when running Loki directly e.g. ./loki as you can get a quick output of the entire Loki config.
-log-config-reverse-order is the flag we run Loki with in all our environments, the config entries are reversed so
that the order of configs reads correctly top to bottom when viewed in Grafana’s Explore.
Configuration File Reference
To specify which configuration file to load, pass the -config.file flag at the
command line. The file is written in
YAML format,
defined by the scheme below. Brackets indicate that a parameter is optional. For
non-list parameters the value is set to the specified default.
Use environment variables in the configuration
Note: This feature is only available in Loki 2.1+.
You can use environment variable references in the configuration file to set values that need to be configurable during deployment.
To do this, pass -config.expand-env=true and use:
${VAR}Where VAR is the name of the environment variable.
Each variable reference is replaced at startup by the value of the environment variable. The replacement is case-sensitive and occurs before the YAML file is parsed. References to undefined variables are replaced by empty strings unless you specify a default value or custom error text.
To specify a default value, use:
${VAR:default_value}Where default_value is the value to use if the environment variable is undefined.
Pass the -config.expand-env flag at the command line to enable this way of setting configs.
Generic placeholders:
<boolean>: a boolean that can take the valuestrueorfalse<int>: any integer matching the regular expression[1-9]+[0-9]*<duration>: a duration matching the regular expression[0-9]+(ns|us|µs|ms|[smh])<labelname>: a string matching the regular expression[a-zA-Z_][a-zA-Z0-9_]*<labelvalue>: a string of unicode characters<filename>: a valid path relative to current working directory or an absolute path.<host>: a valid string consisting of a hostname or IP followed by an optional port number<string>: a regular string<secret>: a regular string that is a secret, such as a password
Supported contents and default values of loki.yaml:
server_config
The server_config block configures the HTTP and gRPC server of the launched service(s):
distributor_config
The distributor_config block configures the Loki Distributor.
# Configures the distributors ring, used when the "global" ingestion rate
# strategy is enabled.
ring:
kvstore:
# The backend storage to use for the ring. Supported values are
# consul, etcd, inmemory, memberlist
# CLI flag: -distributor.ring.store
store: <string>
# The prefix for the keys in the store. Should end with a /.
# CLI flag: -distributor.ring.prefix
[prefix: <string> | default = "collectors/"]
# Configuration for a Consul client. Only applies if store is "consul"
# The CLI flags prefix for this block config is: distributor.ring
[consul: <consul_config>]
# Configuration for an ETCD v3 client. Only applies if store is "etcd"
# The CLI flags prefix for this block config is: distributor.ring
[etcd: <etcd_config>]
# Configuration for Gossip memberlist. Only applies if store is "memberlist"
# The CLI flags prefix for this block config is: distributor.ring
[memberlist: <memberlist_config>]
# The heartbeat timeout after which ingesters are skipped for
# reading and writing.
# CLI flag: -distributor.ring.heartbeat-timeout
[heartbeat_timeout: <duration> | default = 1m]querier_config
The querier_config block configures the Loki Querier.
# Timeout when querying ingesters or storage during the execution of a query request.
# CLI flag: -querier.query-timeout
[query_timeout: <duration> | default = 1m]
# Maximum duration for which the live tailing requests should be served.
# CLI flag: -querier.tail-max-duration
[tail_max_duration: <duration> | default = 1h]
# Time to wait before sending more than the minimum successful query requests.
# CLI flag: -querier.extra-query-delay
[extra_query_delay: <duration> | default = 0s]
# Maximum lookback beyond which queries are not sent to ingester.
# 0 means all queries are sent to ingester.
# CLI flag: -querier.query-ingesters-within
[query_ingesters_within: <duration> | default = 0s]
# Configuration options for the LogQL engine.
engine:
# Timeout for query execution
# CLI flag: -querier.engine.timeout
[timeout: <duration> | default = 3m]
# The maximum amount of time to look back for log lines. Only
# applicable for instant log queries.
# CLI flag: -querier.engine.max-lookback-period
[max_look_back_period: <duration> | default = 30s]query_frontend_config
The query_frontend_config configures the Loki query-frontend.
# Maximum number of outstanding requests per tenant per frontend; requests
# beyond this error with HTTP 429.
# CLI flag: -querier.max-outstanding-requests-per-tenant
[max_outstanding_per_tenant: <int> | default = 100]
# Compress HTTP responses.
# CLI flag: -querier.compress-http-responses
[compress_responses: <boolean> | default = false]
# URL of downstream Loki.
# CLI flag: -frontend.downstream-url
[downstream_url: <string> | default = ""]
# Log queries that are slower than the specified duration. Set to 0 to disable.
# Set to < 0 to enable on all queries.
# CLI flag: -frontend.log-queries-longer-than
[log_queries_longer_than: <duration> | default = 0s]
# URL of querier for tail proxy.
# CLI flag: -frontend.tail-proxy-url
[tail_proxy_url: <string> | default = ""]queryrange_config
The queryrange_config configures the query splitting and caching in the Loki query-frontend.
# Split queries by an interval and execute in parallel, 0 disables it. You
# should use in multiple of 24 hours (same as the storage bucketing scheme),
# to avoid queriers downloading and processing the same chunks. This also
# determines how cache keys are chosen when result caching is enabled
# CLI flag: -querier.split-queries-by-interval
[split_queries_by_interval: <duration> | default = 0s]
# Deprecated: Split queries by day and execute in parallel. Use -querier.split-queries-by-interval instead.
# CLI flag: -querier.split-queries-by-day
[split_queries_by_day: <boolean> | default = false]
# Mutate incoming queries to align their start and end with their step.
# CLI flag: -querier.align-querier-with-step
[align_queries_with_step: <boolean> | default = false]
results_cache:
# The CLI flags prefix for this block config is: frontend
cache: <cache_config>
# Cache query results.
# CLI flag: -querier.cache-results
[cache_results: <boolean> | default = false]
# Maximum number of retries for a single request; beyond this, the downstream
# error is returned.
# CLI flag: -querier.max-retries-per-request
[max_retries: <int> | default = 5]
# Perform query parallelisations based on storage sharding configuration and
# query ASTs. This feature is supported only by the chunks storage engine.
# CLI flag: -querier.parallelise-shardable-queries
[parallelise_shardable_queries: <boolean> | default = false]ruler_config
The ruler_config configures the Loki ruler.
frontend_worker_config
The frontend_worker_config configures the worker - running within the Loki querier - picking up and executing queries enqueued by the query-frontend.
# Address of query frontend service, in host:port format.
# CLI flag: -querier.frontend-address
[frontend_address: <string> | default = ""]
# Number of simultaneous queries to process.
# CLI flag: -querier.worker-parallelism
[parallelism: <int> | default = 10]
# How often to query DNS.
# CLI flag: -querier.dns-lookup-period
[dns_lookup_duration: <duration> | default = 10s]
# The CLI flags prefix for this block config is: querier.frontend-client
[grpc_client_config: <grpc_client_config>]ingester_client_config
The ingester_client_config block configures how connections to ingesters
operate.
# Configures how connections are pooled
pool_config:
# Whether or not to do health checks.
# CLI flag: -distributor.health-check-ingesters
[health_check_ingesters: <boolean> | default = false]
# How frequently to clean up clients for servers that have gone away after
# a health check.
# CLI flag: -distributor.client-cleanup-period
[client_cleanup_period: <duration> | default = 15s]
# How quickly a dead client will be removed after it has been detected
# to disappear. Set this to a value to allow time for a secondary
# health check to recover the missing client.
[remotetimeout: <duration>]
# The remote request timeout on the client side.
# CLI flag: -ingester.client.healthcheck-timeout
[remote_timeout: <duration> | default = 5s]
# Configures how the gRPC connection to ingesters work as a client
# The CLI flags prefix for this block config is: ingester.client
[grpc_client_config: <grpc_client_config>]ingester_config
The ingester_config block configures the Loki Ingesters.
consul_config
The consul_config configures the consul client. The supported CLI flags
# The hostname and port of Consul.
# CLI flag: -<prefix>.consul.hostname
[host: <string> | default = "localhost:8500"]
# The ACL Token used to interact with Consul.
# CLI flag: -<prefix>.consul.acl-token
[acl_token: <string>]
# The HTTP timeout when communicating with Consul
# CLI flag: -<prefix>.consul.client-timeout
[http_client_timeout: <duration> | default = 20s]
# Whether or not consistent reads to Consul are enabled.
# CLI flag: -<prefix>.consul.consistent-reads
[consistent_reads: <boolean> | default = true]etcd_config
The etcd_config configures the etcd client. The supported CLI flags
# The etcd endpoints to connect to.
# CLI flag: -<prefix>.etcd.endpoints
[endpoints: <list of string> | default = []]
# The dial timeout for the etcd connection.
# CLI flag: -<prefix>.etcd.dial-timeout
[dial_timeout: <duration> | default = 10s]
# The maximum number of retries to do for failed ops.
# CLI flag: -<prefix>.etcd.max-retries
[max_retries: <int> | default = 10]memberlist_config
The memberlist_config block configures the gossip ring to discover and connect
between distributors, ingesters and queriers. The configuration is unique for all
three components to ensure a single shared ring.
storage_config
The storage_config block configures one of many possible stores for both the
index and chunks. Which configuration to be picked should be defined in schema_config
block.
chunk_store_config
The chunk_store_config block configures how chunks will be cached and how long
to wait before saving them to the backing store.
# The cache configuration for storing chunks
# The CLI flags prefix for this block config is: store.chunks-cache
[chunk_cache_config: <cache_config>]
# The cache configuration for deduplicating writes
# The CLI flags prefix for this block config is: store.index-cache-write
[write_dedupe_cache_config: <cache_config>]
# The minimum time between a chunk update and being saved
# to the store.
[min_chunk_age: <duration>]
# Cache index entries older than this period. Default is disabled.
# CLI flag: -store.cache-lookups-older-than
[cache_lookups_older_than: <duration>]
# Limit how long back data can be queried. Default is disabled.
# This should always be set to a value less than or equal to
# what is set in `table_manager.retention_period` .
# CLI flag: -store.max-look-back-period
[max_look_back_period: <duration>]cache_config
The cache_config block configures how Loki will cache requests, chunks, and
the index to a backing cache store.
schema_config
The schema_config block configures schemas from given dates.
# The configuration for chunk index schemas.
configs:
- [<period_config>]period_config
The period_config block configures what index schemas should be used
for from specific time periods.
limits_config
The limits_config block configures global and per-tenant limits for ingesting
logs in Loki.
grpc_client_config
The grpc_client_config block configures a client connection to a gRPC service.
table_manager_config
The table_manager_config block configures the Loki table-manager.
# Master 'off-switch' for table capacity updates, e.g. when troubleshooting.
# CLI flag: -table-manager.throughput-updates-disabled
[throughput_updates_disabled: <boolean> | default = false]
# Master 'on-switch' for table retention deletions.
# CLI flag: -table-manager.retention-deletes-enabled
[retention_deletes_enabled: <boolean> | default = false]
# How far back tables will be kept before they are deleted. 0s disables
# deletion. The retention period must be a multiple of the index / chunks
# table "period" (see period_config).
# CLI flag: -table-manager.retention-period
[retention_period: <duration> | default = 0s]
# Period with which the table manager will poll for tables.
# CLI flag: -table-manager.poll-interval
[poll_interval: <duration> | default = 2m]
# Duration a table will be created before it is needed.
# CLI flag: -table-manager.periodic-table.grace-period
[creation_grace_period: <duration> | default = 10m]
# Configures management of the index tables for DynamoDB.
# The CLI flags prefix for this block config is: table-manager.index-table
index_tables_provisioning: <provision_config>
# Configures management of the chunk tables for DynamoDB.
# The CLI flags prefix for this block config is: table-manager.chunk-table
chunk_tables_provisioning: <provision_config>provision_config
The provision_config block configures provisioning capacity for DynamoDB.
auto_scaling_config
The auto_scaling_config block configures autoscaling for DynamoDB.
# Whether or not autoscaling should be enabled.
# CLI flag: -<prefix>.scale.enabled
[enabled: <boolean>: default = false]
# AWS AutoScaling role ARN.
# CLI flag: -<prefix>.scale.role-arn
[role_arn: <string>]
# DynamoDB minimum provision capacity.
# CLI flag: -<prefix>.scale.min-capacity
[min_capacity: <int> | default = 3000]
# DynamoDB maximum provision capacity.
# CLI flag: -<prefix>.scale.max-capacity
[max_capacity: <int> | default = 6000]
# DynamoDB minimum seconds between each autoscale up.
# CLI flag: -<prefix>.scale.out-cooldown
[out_cooldown: <int> | default = 1800]
# DynamoDB minimum seconds between each autoscale down.
# CLI flag: -<prefix>.scale.in-cooldown
[in_cooldown: <int> | default = 1800]
# DynamoDB target ratio of consumed capacity to provisioned capacity.
# CLI flag: -<prefix>.scale.target-value
[target: <float> | default = 80]tracing_config
The tracing_config block configures tracing for Jaeger. Currently limited to disable auto-configuration per
environment variables only.
# Whether or not tracing should be enabled.
# CLI flag: -tracing.enabled
[enabled: <boolean>: default = true]Runtime Configuration file
Loki has a concept of “runtime config” file, which is simply a file that is reloaded while Loki is running. It is used by some Loki components to allow operator to change some aspects of Loki configuration without restarting it. File is specified by using -runtime-config.file=<filename> flag and reload period (which defaults to 10 seconds) can be changed by -runtime-config.reload-period=<duration> flag. Previously this mechanism was only used by limits overrides, and flags were called -limits.per-user-override-config=<filename> and -limits.per-user-override-period=10s respectively. These are still used, if -runtime-config.file=<filename> is not specified.
At the moment, two components use runtime configuration: limits and multi KV store.
Options for runtime configuration reload can also be configured via YAML:
# Configuration file to periodically check and reload.
[file: <string>: default = empty]
# How often to check the file.
[period: <duration>: default 10 seconds]Example runtime configuration file:
overrides:
tenant1:
ingestion_rate_mb: 10
max_streams_per_user: 100000
max_chunks_per_query: 100000
tenant2:
max_streams_per_user: 1000000
max_chunks_per_query: 1000000
multi_kv_config:
mirror-enabled: false
primary: consulGeneric placeholders
Was this page helpful?
Related resources from Grafana Labs
