--- title: "Configure Promtail | Grafana Enterprise Logs documentation" description: "Configuration parameters for the Promtail agent." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Configure Promtail > Caution > > Promtail has been deprecated and is in Long-Term Support (LTS) through February 28, 2026. Promtail will reach an End-of-Life (EOL) on March 2, 2026. You can find migration resources [here](/docs/alloy/latest/set-up/migrate/from-promtail/). Promtail is configured in a YAML file (usually referred to as `config.yaml`) which contains information on the Promtail server, where positions are stored, and how to scrape logs from files. ## Printing Promtail Config At Runtime If you pass Promtail the flag `-print-config-stderr` or `-log-config-reverse-order`, (or `-print-config-stderr=true`) Promtail 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 Promtail config struct. Some values may not be relevant to your install, this is expected as every option has a default value if it is being used or not. This config is what Promtail 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 Promtail directly e.g. `./promtail`as you can get a quick output of the entire Promtail config. `-log-config-reverse-order` is the flag we run Promtail 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](https://en.wikipedia.org/wiki/YAML), defined by the schema below. Brackets indicate that a parameter is optional. For non-list parameters the value is set to the specified default. For more detailed information on configuring how to discover and scrape logs from targets, see [Scraping](../scraping/). For more information on transforming logs from scraped targets, see [Pipelines](../pipelines/). ## Reload at runtime Promtail can reload its configuration at runtime. If the new configuration is not well-formed, the changes will not be applied. A configuration reload is triggered by sending a `SIGHUP` to the Promtail process or sending a HTTP POST request to the `/reload` endpoint (when the `--server.enable-runtime-reload` flag is enabled). ### Use environment variables in the configuration 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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none ${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: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none ${VAR:-default_value} ``` Where default\_value is the value to use if the environment variable is undefined. > Note > > With `expand-env=true` the configuration will first run through [envsubst](https://pkg.go.dev/github.com/drone/envsubst) which will replace double backslashes with single backslashes. Because of this every use of a backslash `\` needs to be replaced with a double backslash `\\`. ### Generic placeholders - ``: a boolean that can take the values `true` or `false` - ``: any integer matching the regular expression `[1-9]+[0-9]*` - ``: a duration matching the regular expression `[0-9]+(ms|[smhdwy])` - ``: a string matching the regular expression `[a-zA-Z_][a-zA-Z0-9_]*` - ``: a string of Unicode characters - ``: a valid path relative to current working directory or an absolute path. - ``: a valid string consisting of a hostname or IP followed by an optional port number - ``: a string - ``: a string that represents a secret, such as a password ### Supported contents and default values of `config.yaml`: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Configures global settings which impact all targets. [global: ] # Configures the server for Promtail. [server: ] # Describes how Promtail connects to multiple instances # of Grafana Loki, sending logs to each. # WARNING: If one of the remote Loki servers fails to respond or responds # with any error which is retryable, this will impact sending logs to any # other configured remote Loki servers. Sending is done on a single thread! # It is generally recommended to run multiple Promtail clients in parallel # if you want to send to multiple remote Loki instances. clients: - [] # Describes how to save read file offsets to disk [positions: ] scrape_configs: - [] # Configures global limits for this instance of Promtail [limits_config: ] # Configures how tailed targets will be watched. [target_config: ] # Configures additional promtail configurations. [options: ] # Configures tracing support [tracing: ] ``` ## global The `global` block configures global settings which impact all scrape targets: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Configure how frequently log files from disk get polled for changes. [file_watch_config: ] ``` ## file\_watch\_config The `file_watch_config` block configures how often to poll log files from disk for changes: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Minimum frequency to poll for files. Any time file changes are detected, the # poll frequency gets reset to this duration. [min_poll_frequency: | default = "250ms"] # Maximum frequency to poll for files. Any time no file changes are detected, # the poll frequency doubles in value up to the maximum duration specified by # this value. # # The default is set to the same as min_poll_frequency. [max_poll_frequency: | default = "250ms"] ``` ## server The `server` block configures Promtail’s behavior as an HTTP server: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Disable the HTTP and GRPC server. [disable: | default = false] # Enable the /debug/fgprof and /debug/pprof endpoints for profiling. [profiling_enabled: | default = false] # HTTP server listen host [http_listen_address: ] # HTTP server listen port (0 means random port) [http_listen_port: | default = 80] # gRPC server listen host [grpc_listen_address: ] # gRPC server listen port (0 means random port) [grpc_listen_port: | default = 9095] # Register instrumentation handlers (/metrics, etc.) [register_instrumentation: | default = true] # Timeout for graceful shutdowns [graceful_shutdown_timeout: | default = 30s] # Read timeout for HTTP server [http_server_read_timeout: | default = 30s] # Write timeout for HTTP server [http_server_write_timeout: | default = 30s] # Idle timeout for HTTP server [http_server_idle_timeout: | default = 120s] # Max gRPC message size that can be received [grpc_server_max_recv_msg_size: | default = 4194304] # Max gRPC message size that can be sent [grpc_server_max_send_msg_size: | default = 4194304] # Limit on the number of concurrent streams for gRPC calls (0 = unlimited) [grpc_server_max_concurrent_streams: | default = 100] # Log only messages with the given severity or above. Supported values [debug, # info, warn, error] [log_level: | default = "info"] # Base path to server all API routes from (e.g., /v1/). [http_path_prefix: ] # Target managers check flag for Promtail readiness, if set to false the check is ignored [health_check_target: | default = true] # Enable reload via HTTP request. [enable_runtime_reload: | default = false] ``` ## clients The `clients` block configures how Promtail connects to instances of Loki: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # The URL where Loki is listening, denoted in Loki as http_listen_address and # http_listen_port. If Loki is running in microservices mode, this is the HTTP # URL for the Distributor. Path to the push API needs to be included. # Example: http://example.com:3100/loki/api/v1/push url: # Custom HTTP headers to be sent along with each push request. # Be aware that headers that are set by Promtail itself (e.g. X-Scope-OrgID) can't be overwritten. headers: # Example: CF-Access-Client-Id: xxx [ : ... ] # The tenant ID used by default to push logs to Loki. If omitted or empty # it assumes Loki is running in single-tenant mode and no X-Scope-OrgID header # is sent. [tenant_id: ] # Maximum amount of time to wait before sending a batch, even if that # batch isn't full. [batchwait: | default = 1s] # Maximum batch size (in bytes) of logs to accumulate before sending # the batch to Loki. [batchsize: | default = 1048576] # If using basic auth, configures the username and password # sent. basic_auth: # The username to use for basic auth [username: ] # The password to use for basic auth [password: ] # The file containing the password for basic auth [password_file: ] # Optional OAuth 2.0 configuration # Cannot be used at the same time as basic_auth or authorization oauth2: # Client id and secret for oauth2 [client_id: ] [client_secret: ] # Read the client secret from a file # It is mutually exclusive with `client_secret` [client_secret_file: ] # Optional scopes for the token request scopes: [ - ... ] # The URL to fetch the token from token_url: # Optional parameters to append to the token URL endpoint_params: [ : ... ] # Bearer token to send to the server. [bearer_token: ] # File containing bearer token to send to the server. [bearer_token_file: ] # HTTP proxy server to use to connect to the server. [proxy_url: ] # If connecting to a TLS server, configures how the TLS # authentication handshake will operate. tls_config: # The CA file to use to verify the server [ca_file: ] # The cert file to send to the server for client auth [cert_file: ] # The key file to send to the server for client auth [key_file: ] # Validates that the server name in the server's certificate # is this value. [server_name: ] # If true, ignores the server certificate being signed by an # unknown CA. [insecure_skip_verify: | default = false] # Configures how to retry requests to Loki when a request # fails. # Default backoff schedule: # 0.5s, 1s, 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s(4.267m) # For a total time of 511.5s(8.5m) before logs are lost backoff_config: # Initial backoff time between retries [min_period: | default = 500ms] # Maximum backoff time between retries [max_period: | default = 5m] # Maximum number of retries to do [max_retries: | default = 10] # Disable retries of batches that Loki responds to with a 429 status code (TooManyRequests). This reduces # impacts on batches from other tenants, which could end up being delayed or dropped due to exponential backoff. [drop_rate_limited_batches: | default = false] # Static labels to add to all logs being sent to Loki. # Use map like {"foo": "bar"} to add a label foo with # value bar. # These can also be specified from command line: # -client.external-labels=k1=v1,k2=v2 # (or --client.external-labels depending on your OS) # labels supplied by the command line are applied # to all clients configured in the `clients` section. # NOTE: values defined in the config file will replace values # defined on the command line for a given client if the # label keys are the same. external_labels: [ : ... ] # Maximum time to wait for a server to respond to a request [timeout: | default = 10s] ``` ## positions The `positions` block configures where Promtail will save a file indicating how far it has read into a file. It is needed for when Promtail is restarted to allow it to continue from where it left off. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Location of positions file [filename: | default = "/var/log/positions.yaml"] # How often to update the positions file [sync_period: | default = 10s] # Whether to ignore & later overwrite positions files that are corrupted [ignore_invalid_yaml: | default = false] ``` ## scrape\_configs The `scrape_configs` block configures how Promtail can scrape logs from a series of targets using a specified discovery method. Promtail uses the same [Prometheus scrape\_configs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config). This means if you already own a Prometheus instance, the config will be very similar: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # Name to identify this scrape config in the Promtail UI. job_name: # Describes how to transform logs from targets. [pipeline_stages: ] # Defines decompression behavior for the given scrape target. decompression: # Whether decompression should be tried or not. [enabled: | default = false] # Initial delay to wait before starting the decompression. # Especially useful in scenarios where compressed files are found before the compression is finished. [initial_delay: | default = 0s] # Compression format. Supported formats are: 'gz', 'bz2' and 'z. [format: | default = ""] # Describes how to scrape logs from the journal. [journal: ] # Describes from which encoding a scraped file should be converted. [encoding: ] # Describes how to receive logs from syslog. [syslog: ] # Describes how to receive logs via the Loki push API, (e.g. from other Promtails or the Docker Logging Driver) [loki_push_api: ] # Describes how to scrape logs from the Windows event logs. [windows_events: ] # Configuration describing how to pull/receive Google Cloud Platform (GCP) logs. [gcplog: ] # Configuration describing how to get Azure Event Hubs messages. [azure_event_hub: ] # Describes how to fetch logs from Kafka via a Consumer group. [kafka: ] # Describes how to receive logs from gelf client. [gelf: ] # Configuration describing how to pull logs from Cloudflare. [cloudflare: ] # Configuration describing how to pull logs from a Heroku LogPlex drain. [heroku_drain: ] # Describes how to relabel targets to determine if they should # be processed. relabel_configs: - [] # Static targets to scrape. static_configs: - [] # Files containing targets to scrape. file_sd_configs: - [] # Describes how to discover Kubernetes services running on the # same host. kubernetes_sd_configs: - [] # Describes how to use the Consul Catalog API to discover services registered with the # consul cluster. consul_sd_configs: [ - ... ] # Describes how to use the Consul Agent API to discover services registered with the consul agent # running on the same host as Promtail. consulagent_sd_configs: [ - ... ] # Describes how to use the Docker daemon API to discover containers running on # the same host as Promtail. docker_sd_configs: [ - ... ] ``` ### pipeline\_stages [Pipeline](../pipelines/) stages are used to transform log entries and their labels. The pipeline is executed after the discovery process finishes. The `pipeline_stages` object consists of a list of stages which correspond to the items listed below. In most cases, you extract data from logs with `regex` or `json` stages. The extracted data is transformed into a temporary map object. The data can then be used by Promtail e.g. as values for `labels` or as an `output`. Additionally any other stage aside from `docker` and `cri` can access the extracted data. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml - [ | | | |