loki on Grafana Labs

loki.echo

Mon, 30 Mar 2026 15:47:22 +0000

`loki.echo`

loki.echo receives log entries from other loki components and prints them to the process’ standard output, stdout.

You can specify multiple loki.echo components by giving them different labels.

Usage

loki.echo "<LABEL>" {}

Arguments

The loki.echo component doesn’t support any arguments.

Blocks

The loki.echo component doesn’t support any blocks.

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`receiver`	`LogsReceiver`	A value that other components can use to send log entries to.

Component health

loki.echo is only reported as unhealthy if given an invalid configuration.

Debug information

loki.echo doesn’t expose any component-specific debug information.

Example

This example creates a pipeline that reads log files from /var/log and prints log lines to echo:

local.file_match "varlog" {
  path_targets = [{
    __path__ = "/var/log/*log",
    job      = "varlog",
  }]
}

loki.source.file "logs" {
  targets    = local.file_match.varlog.targets
  forward_to = [loki.echo.example.receiver]
}

loki.echo "example" { }

Compatible components

loki.echo has exports that can be consumed by the following components:

Components that consume Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.enrich

Mon, 30 Mar 2026 15:47:22 +0000

`loki.enrich`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

The loki.enrich component enriches logs with additional labels from service discovery targets. It matches a label from incoming logs against a label from discovered targets, and copies specified labels from the matched target to the log entry.

Usage

loki.enrich "<LABEL>" {
  // List of targets from a discovery component
  targets = <DISCOVERY_COMPONENT>.targets
  
  // Which label from discovered targets to match against
  target_match_label = "<LABEL>"
  
  // Which label from incoming logs to match against
  logs_match_label = "<LABEL>"
  
  // List of labels to copy from discovered targets to logs
  labels_to_copy = ["<LABEL>", ...]
  
  // Where to send enriched logs
  forward_to = [<RECEIVER_LIST>]
}

Arguments

You can use the following arguments with loki.enrich:

Name	Type	Description	Required
`forward_to`	`[]loki.LogsReceiver`	List of receivers to send enriched logs to.	yes
`target_match_label`	`string`	The label from discovered targets to match against, for example, `"__inventory_consul_service"`.	yes
`targets`	`[]discovery.Target`	List of targets from a discovery component.	yes
`labels_to_copy`	`[]string`	List of labels to copy from discovered targets to logs. If empty, all labels will be copied.	no
`logs_match_label`	`string`	The label from incoming logs to match against discovered targets, for example `"service_name"`.	no

If not provided, the logs_match_label attribute will default to the value of target_match_label.

Blocks

The loki.enrich component doesn’t support any blocks. You can configure this component with arguments.

Exports

The following values are exported:

Name	Type	Description
`receiver`	`loki.LogsReceiver`	A receiver that can be used to send logs to this component.

Example

// Configure HTTP discovery
discovery.http "default" {
    url = "http://network-inventory.example.com/prometheus_sd"
}

discovery.relabel "default" {
    targets = discovery.http.default.targets
    rule {
        action        = "replace"
        source_labels = ["__inventory_rack"]
        target_label  = "rack"
    }
    rule {
        action        = "replace"
        source_labels = ["__inventory_datacenter"]
        target_label  = "datacenter"
    }
    rule {
        action        = "replace"
        source_labels = ["__inventory_environment"]
        target_label  = "environment"
    }
    rule {
        action        = "replace"
        source_labels = ["__inventory_tenant"]
        target_label  = "tenant"
    }
    rule {
        action        = "replace"
        source_labels = ["__inventory_primary_ip"]
        target_label  = "primary_ip"
    }
}

// Receive syslog messages
loki.source.syslog "incoming" {
    listener {
        address = ":514"
        protocol = "tcp"
        labels = {
            job = "syslog"
        }
    }
    forward_to = [loki.enrich.default.receiver]
}

// Enrich logs using HTTP discovery
loki.enrich "default" {
    // Use targets from HTTP discovery (after relabeling)
    targets = discovery.relabel.default.output

    // Match hostname from logs to DNS name
    target_match_label = "primary_ip"

    forward_to = [loki.write.default.receiver]
}

Component Behavior

The component matches logs to discovered targets and enriches them with additional labels:

For each log entry, it looks up the value of logs_match_label from the log’s labels or target_match_label if logs_match_label is not specified.
It matches this value against the target_match_label in discovered targets.
If a match is found, it copies the requested labels_to_copy from the discovered target to the log entry. If labels_to_copy is empty, all labels are copied.
The log entry, enriched or unchanged, is forwarded to the configured receivers.

Caution
By default, loki.enrich is ready as soon as it starts, even if no targets have been discovered. If telemetry is sent to this component before the metadata is synced, then it will be passed though as-is, without enrichment. This is most likely to impact loki.enrich on startup for a short time before the discovery components have sent a new list of targets.

Compatible components

loki.enrich can accept arguments from the following components:

Components that export Targets
Components that export Loki LogsReceiver

loki.enrich has exports that can be consumed by the following components:

Components that consume Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.process

Mon, 13 Apr 2026 07:37:47 +0000

`loki.process`

loki.process receives log entries from other loki components, applies one or more processing stages, and forwards the results to the list of receivers in the component’s arguments.

A stage is a multi-purpose tool that can parse, transform, and filter log entries before they’re passed to a downstream component. These stages are applied to each log entry in order of their appearance in the configuration file. All stages within a loki.process block have access to the log entry’s label set, the log line, the log timestamp, as well as a shared map of ’extracted’ values so that the results of one stage can be used in a subsequent one.

You can specify multiple loki.process components by giving them different labels.

Usage

loki.process "<LABEL>" {
  forward_to = <RECEIVER_LIST>

  stage.<STAGENAME> {
    ...
  }
  ...
}

Arguments

You can use the following argument with loki.process:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	Where to forward log entries after processing.		yes

Blocks

You can use the following blocks with loki.process:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

You can provide any number of these stage blocks nested inside loki.process. These blocks run in order of appearance in the configuration file.

`stage.cri`

The stage.cri inner block enables a predefined pipeline which reads log lines using the CRI logging format.

The following arguments are supported:

Name	Type	Description	Default	Required
`max_partial_line_size_truncate`	`bool`	Truncate partial lines that are longer than `max_partial_line_size`.	`false`	no
`max_partial_line_size`	`number`	Maximum number of characters which a partial line can have.	`0`	no
`max_partial_lines`	`number`	Maximum number of partial lines to hold in memory.	`100`	no

max_partial_line_size is only taken into account if max_partial_line_size_truncate is set to true.

stage.cri {}

CRI specifies log lines as single space-delimited values with the following components:

time: The timestamp string of the log.
stream: Either stdout or stderr.
flags: CRI flags including F or P.
log: The contents of the log line.

Given the following log line, the subsequent key-value pairs are created in the shared map of extracted data:

"2019-04-30T02:12:41.8443515Z stdout F message"

content: message
stream: stdout
time: 2019-04-30T02:12:41.8443515

`stage.decolorize`

The stage.decolorize strips ANSI color codes from the log lines, making it easier to parse logs.

The stage.decolorize block doesn’t support any arguments or inner blocks, so it’s always empty.

stage.decolorize {}

stage.decolorize turns each line having a color code into a non-colored one. For example:

[2022-11-04 22:17:57.811] \033[0;32http\033[0m: GET /_health (0 ms) 204

is turned into

[2022-11-04 22:17:57.811] http: GET /_health (0 ms) 204

`stage.docker`

The stage.docker inner block enables a predefined pipeline which reads log lines in the standard format of Docker log files.

The stage.docker block doesn’t support any arguments or inner blocks, so it’s always empty.

stage.docker {}

Docker log entries are formatted as JSON with the following keys:

log: The content of log line.
stream: Either stdout or stderr.
time: The timestamp string of the log line.

Given the following log line, the subsequent key-value pairs are created in the shared map of extracted data:

{"log":"log message\n","stream":"stderr","time":"2019-04-30T02:12:41.8443515Z"}

output: log message\n
stream: stderr
timestamp: 2019-04-30T02:12:41.8443515

`stage.drop`

The stage.drop inner block configures a filtering stage that drops log entries based on several options. If multiple options are provided, they’re treated as AND clauses and must all be true for the log entry to be dropped. To drop entries with an OR clause, specify multiple drop blocks in sequence.

The following arguments are supported:

Name	Type	Description	Default	Required
`drop_counter_reason`	`string`	A custom reason to report for dropped lines.	`"drop_stage"`	no
`expression`	`string`	A valid RE2 regular expression.	`""`	no
`longer_than`	`string`	If specified, the stage drops lines whose size exceeds the configured value.	`""`	no
`older_than`	`duration`	If specified, the stage drops lines whose timestamp is older than the current time minus this duration.	`""`	no
`separator`	`string`	When `source` is a comma-separated list of names, this separator is placed between concatenated extracted data values.	`";"`	no
`source`	`string`	Name or comma-separated list of names from extracted data to match. If empty or not defined, it uses the log message.	`""`	no
`value`	`string`	If both `source` and `value` are specified, the stage drops lines where `value` exactly matches the source content.	`""`	no

The expression field must be a RE2 regular expression string.

If source is empty or not provided, the regular expression attempts to match the log line itself.
If source is a single name, the regular expression attempts to match the corresponding value from the extracted map.
If source is a comma-separated list of names, the corresponding values from the extracted map are concatenated using separator and the regular expression attempts to match the concatenated string.

The value field can only work with values from the extracted map, and must be specified together with source.

If source is a single name, the entries are dropped when there is an exact match between the corresponding value from the extracted map and the value.
If source is a comma-separated list of names, the entries are dropped when the value matches the source values from extracted data, concatenated using the separator.

Whenever an entry is dropped, the metric loki_process_dropped_lines_total is incremented. By default, the reason label is "drop_stage", but you can provide a custom label using the drop_counter_reason argument.

The following stage drops log entries that contain the word debug and are longer than 1KB.

stage.drop {
    expression  = ".*debug.*"
    longer_than = "1KB"
}

The following example defines multiple drop blocks so loki.process drops entries that are either 24h or older, are longer than 8KB, or the extracted value of app is equal to example.

stage.drop {
    older_than          = "24h"
    drop_counter_reason = "too old"
}

stage.drop {
    longer_than         = "8KB"
    drop_counter_reason = "too long"
}

stage.drop {
    source = "app"
    value  = "example"
}

`stage.eventlogmessage`

Deprecated in favor of the [stage.windowsevent][stage.windowsevent] block.

The eventlogmessage stage extracts data from the Message string that appears in the Windows Event Log.

The following arguments are supported:

Name	Type	Description	Default	Required
`drop_invalid_labels`	`bool`	Whether to drop fields that aren’t valid label names.	`false`	no
`overwrite_existing`	`bool`	Whether to overwrite existing extracted data fields.	`false`	no
`source`	`string`	Name of the field in the extracted data to parse.	`"message"`	no

When drop_invalid_labels is set to true, the stage drops fields that aren’t valid label names. If set to false, the stage automatically converts them into valid labels replacing invalid characters with underscores.

When overwrite_existing is set to true, the stage overwrites existing extracted data fields with the same name. If set to false, the _extracted suffix is appended to an existing field name.

The eventlogmessage stage only extracts lines with the key:value format. All non-alpha characters in the key are replaced with underscores. For example, \tSecurity ID is extracted as _Security_ID.

Example combined with `stage.json`

stage.json {
    expressions = {
        message = "",
        Overwritten = "",
    }
}

stage.eventlogmessage {
    source = "message"
    overwrite_existing = true
}

Given the following log line:

{"event_id": 1, "Overwritten": "old", "message": "Message type:\r\nOverwritten: new\r\nImage: C:\\Users\\User\\alloy.exe"}

The first stage would create the following key-value pairs in the set of extracted data:

message: Message type:\r\nOverwritten: new\r\nImage: C:\Users\User\alloy.exe
Overwritten: old

The second stage parses the value of message from the extracted data and appends or overwrites the following key-value pairs to the set of extracted data:

Image: C:\\Users\\User\\alloy.exe
Message_type: (empty string)
Overwritten: new

`stage.geoip`

The stage.geoip inner block configures a processing stage that reads an IP address and populates the shared map with geoip fields. The Maxmind GeoIP2 database is used for the lookup.

The following arguments are supported:

Name	Type	Description	Required
`db`	`string`	Path to the Maxmind DB file.	yes
`source`	`string`	IP from extracted data to parse.	yes
`custom_lookups`	`map(string)`	Key-value pairs of JMESPath expressions.	no
`db_type`	`string`	Maxmind DB type. Allowed values are `"city"`, `"asn"`, `"country"`.	no

GeoIP with City database example

{"log":"log message","client_ip":"34.120.177.193"}

loki.process "example" {
    stage.json {
        expressions = {ip = "client_ip"}
    }

    stage.geoip {
        source  = "ip"
        db      = "/path/to/db/GeoLite2-City.mmdb"
        db_type = "city"
    }

    stage.labels {
        values = {
            geoip_city_name          = "",
            geoip_country_name       = "",
            geoip_country_code       = "",
            geoip_continent_name     = "",
            geoip_continent_code     = "",
            geoip_location_latitude  = "",
            geoip_location_longitude = "",
            geoip_postal_code        = "",
            geoip_timezone           = "",
            geoip_subdivision_name   = "",
            geoip_subdivision_code   = "",
        }
    }
}

The json stage extracts the IP address from the client_ip key in the log line. Then the extracted ip value is given as source to geoip stage. The geoip stage performs a lookup on the IP and populates the following fields in the shared map which are added as labels using the labels stage.

The extracted data from the IP used in this example:

geoip_city_name: Kansas City
geoip_country_name: United States
geoip_country_code: US
geoip_continent_name: North America
geoip_continent_code: NA
geoip_location_latitude: 39.1027
geoip_location_longitude: -94.5778
geoip_postal_code: 64184
geoip_timezone: America/Chicago
geoip_subdivision_name: Missouri
geoip_subdivision_code: MO

GeoIP with ASN (Autonomous System Number) database example

loki.process "example" {
    stage.json {
        expressions = {ip = "client_ip"}
    }

    stage.geoip {
        source  = "ip"
        db      = "/path/to/db/GeoIP2-ASN.mmdb"
        db_type = "asn"
    }

    stage.labels {
        values = {
            geoip_autonomous_system_number       = "",
            geoip_autonomous_system_organization = "",
        }
    }
}

The extracted data from the IP used in this example:

geoip_autonomous_system_number: 396982
geoip_autonomous_system_organization: GOOGLE-CLOUD-PLATFORM

GeoIP with Country database example

{"log":"log message","client_ip":"34.120.177.193"}

loki.process "example" {
    stage.json {
        expressions = {ip = "client_ip"}
    }

    stage.geoip {
        source  = "ip"
        db      = "/path/to/db/GeoLite2-Country.mmdb"
        db_type = "country"
    }

    stage.labels {
        values = {
            geoip_country_name       = "",
            geoip_country_code       = "",
            geoip_continent_name     = "",
            geoip_continent_code     = "",
        }
    }
}

The extracted data from the IP used in this example:

geoip_country_name: United States
geoip_country_code: US
geoip_continent_name: North America
geoip_continent_code: NA

GeoIP with custom fields example

If the MMDB file used is enriched with custom data, for example, private IP addresses as explained in the Maxmind blog post, then it can be extracted from the record using the custom_lookups attribute.

loki.process "example" {
    stage.json {
        expressions = {ip = "client_ip"}
    }

    stage.geoip {
        source         = "ip"
        db             = "/path/to/db/GeoIP2-Enriched.mmdb"
        db_type        = "city"
        custom_lookups = {
            "department"  = "MyCompany.DeptName",
            "parent_vnet" = "MyCompany.ParentVNet",
            "subnet"      = "MyCompany.Subnet",
        }
    }

    stage.labels {
        values = {
            department  = "",
            parent_vnet = "",
            subnet      = "",
        }
    }
}

The json stage extracts the IP address from the client_ip key in the log line. Then the extracted ip value is given as source to geoip stage. The geoip stage performs a lookup on the IP and populates the shared map with the data from the city database results in addition to the custom lookups. Lastly, the custom lookup fields from the shared map are added as labels.

`stage.json`

The stage.json inner block configures a JSON processing stage that parses incoming log lines or previously extracted values as JSON and uses JMESPath expressions to extract new values from them.

The following arguments are supported:

Name	Type	Description	Default	Required
`expressions`	`map(string)`	Key-value pairs of JMESPath expressions.		yes
`drop_malformed`	`bool`	Drop lines whose input can’t be parsed as valid JSON.	`false`	no
`source`	`string`	Source of the data to parse as JSON.	`""`	no

The expressions field is the set of key-value pairs of JMESPath expressions to run. The map key defines the name with which the data is extracted, while the map value is the expression used to populate the value.

When configuring a JSON stage, the source field defines the source of data to parse as JSON. By default, this is the log line itself, but it can also be a previously extracted value.

The following example shows a given log line and two JSON stages.

{"log":"log message\n","extra":"{\"user\":\"alloy\"}"}

loki.process "username" {
  stage.json {
      expressions = {output = "log", extra = ""}
  }

  stage.json {
      source      = "extra"
      expressions = {username = "user"}
  }
}

In this example, the first stage uses the log line as the source and populates these values in the shared map. An empty expression means using the same value as the key, for example extra="extra".

output: log message\n
extra: {"user": "alloy"}

The second stage uses the value in extra as the input and appends the following key-value pair to the set of extracted data.

username: alloy

Note
Due to a limitation of the upstream jmespath library, you must wrap any string that contains a hyphen - in quotes so that it’s not considered a numerical expression.

If you don’t use quotes to wrap a string that contains a hyphen, you will get errors like: Unexpected token at the end of the expression: tNumber

You can use one of two options to circumvent this issue:

An escaped double quote. For example: http_user_agent = "\"request_User-Agent\""

A backtick quote. For example: http_user_agent = `"request_User-Agent"`

`stage.label_drop`

The stage.label_drop inner block configures a processing stage that drops labels from incoming log entries.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`list(string)`	Configures a `label_drop` processing stage.	`{}`	no

stage.label_drop {
    values = [ "kubernetes_node_name", "kubernetes_namespace" ]
}

`stage.label_keep`

The stage.label_keep inner block configures a processing stage that filters the label set of an incoming log entry down to a subset.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`list(string)`	Configures a `label_keep` processing stage.	`{}`	no

stage.label_keep {
    values = [ "kubernetes_pod_name", "kubernetes_pod_container_name" ]
}

`stage.labels`

The stage.labels inner block configures a labels processing stage that can read data from the extracted values map or structured metadata and set new labels on incoming log entries.

For labels that are static, refer to [stage.static_labels][stage.static_labels]

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`map(string)`	Configures a `labels` processing stage.	`{}`	no
`source_type`	`string`	Where to retrieve the data from. Allowed values are `"extracted"` (default) or `"structured_metadata"`.	`"extracted"`	no

In a labels stage, the map’s keys define the label to set and the values are how to look them up. If the value is empty, it’s inferred to be the same as the key.

stage.labels {
    values = {
      env  = "",         // Sets up an 'env' label, based on the 'env' extracted value.
      user = "username", // Sets up a 'user' label, based on the 'username' extracted value.
    }
}

stage.labels {
    source_type = "structured_metadata"
    values      = {
      env  = "",         // Sets up an 'env' label, based on the 'env' structured metadata value.
      user = "username", // Sets up a 'user' label, based on the 'username' structured metadata value.
    }
}

// Drop the converted structured metadata
stage.structured_metadata_drop {
    values = [ "env", "username" ]
}

`stage.limit`

The stage.limit inner block configures a rate-limiting stage that throttles logs based on several options.

The following arguments are supported:

Name	Type	Description	Default	Required
`burst`	`number`	The maximum number of burst lines that the stage forwards.		yes
`rate`	`number`	The maximum rate of lines per second that the stage forwards.		yes
`by_label_name`	`string`	The label to use when rate-limiting on a label name.	`""`	no
`drop`	`bool`	Whether to discard or backpressure lines that exceed the rate limit.	`false`	no
`max_distinct_labels`	`number`	The number of unique values to keep track of when rate-limiting `by_label_name`.	`10000`	no

The rate limiting is a “token bucket” of size burst. It’s initially full and refilled at rate tokens per second. Each received log entry consumes one token from the bucket. When drop is set to true, incoming entries that exceed the rate-limit are dropped, otherwise they’re queued until more tokens are available.

stage.limit {
    rate  = 5
    burst = 10
}

If by_label_name is set, then drop must be set to true. This enables the stage to rate-limit not by the number of lines but by the number of labels.

The following example rate-limits entries from each unique namespace value independently. Any entries without the namespace label aren’t rate-limited. The stage keeps track of up to max_distinct_labels unique values, defaulting at 10000.

stage.limit {
    rate  = 10
    burst = 10
    drop  = true

    by_label_name = "namespace"
}

`stage.logfmt`

The stage.logfmt inner block configures a processing stage that reads incoming log lines as logfmt and extracts values from them.

The following arguments are supported:

Name	Type	Description	Default	Required
`mapping`	`map(string)`	Key-value pairs of `logmft` fields to extract.		yes
`source`	`string`	Source of the data to parse as `logfmt`.	`""`	no

The source field defines the source of data to parse as logfmt. When source is missing or empty, the stage parses the log line itself, but it can also be used to parse a previously extracted value.

This stage uses the go-logfmt unmarshaler, so that numeric or boolean types are unmarshalled into their correct form. The stage doesn’t perform any other type conversions. If the extracted value is a complex type, it’s treated as a string.

The following log line and stages demonstrates how this works.

time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="this is a log line" extra="user=example_name"

stage.logfmt {
    mapping = { "extra" = "" }
}

stage.logfmt {
    mapping = { "username" = "user" }
    source  = "extra"
}

The first stage parses the log line itself and inserts the extra key in the set of extracted data, with the value of user=example_name.

The second stage parses the contents of extra and appends the username: example_name key-value pair to the set of extracted data.

`stage.luhn`

The stage.luhn inner block configures a processing stage that reads incoming log lines and redacts strings that match a Luhn algorithm.

The Luhn algorithm is a simple checksum formula used to validate various identification numbers, such as credit card numbers, IMEI numbers, National Provider Identifier numbers in the USA, and Canadian Social Insurance Numbers. Many Payment Card Industry environments require these numbers to be redacted.

The following arguments are supported:

Name	Type	Description	Default	Required
`delimiters`	`string`	A list containing delimiters to accept as part of the number.	`""`	no
`min_length`	`int`	Minimum length of digits to consider	`13`	no
`replacement`	`string`	String to substitute the matched patterns with.	`"REDACTED"`	no
`source`	`string`	Source of the data to parse.	`""`	no

The source field defines the source of data to search. When source is missing or empty, the stage parses the log line itself, but it can also be used to parse a previously extracted value.

If you want the Luhn algorithm to identify numbers with delimiters, for example 4032-0325-1354-8443, you can configure the delimiters field with the expected delimiters.

Example

The following example log line contains an approved credit card number.

time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="credit card approved 4032032513548443" extra="user=example_name"

stage.luhn {
    replacement = "**DELETED**"
}

The stage parses the log line, redacts the credit card number, and produces the following updated log line:

time=2012-11-01T22:08:41+00:00 app=loki level=INFO duration=125 message="credit card approved **DELETED**" extra="user=example_name"

Example with `delimiters`

The following example log line contains an approved credit card number, represented with dash characters between each group of four digits.

time=2012-11-01T22:08:41+00:00 app=loki level=WARN duration=125 message="credit card approved 4032-0325-1354-8443" extra="user=example_name"

stage.luhn {
    replacement = "**DELETED**"
    delimiters = "-"
}

The stage parses the log line, redacts the credit card number, and produces the following updated log line:

time=2012-11-01T22:08:41+00:00 app=loki level=INFO duration=125 message="credit card approved **DELETED**" extra="user=example_name"

`stage.match`

The stage.match inner block configures a filtering stage that can conditionally either apply a nested set of processing stages or drop an entry when a log entry matches a configurable LogQL stream selector and filter expressions.

The following arguments are supported:

Name	Type	Description	Default	Required
`selector`	`string`	The LogQL stream selector and line filter expressions to use.		yes
`action`	`string`	The action to take when the selector matches the log line. Supported values are `"keep"` and `"drop"`	`"keep"`	no
`drop_counter_reason`	`string`	A custom reason to report for dropped lines.	`"match_stage"`	no
`pipeline_name`	`string`	A custom name to use for the nested pipeline.	`""`	no

Note
The filters don’t include label filter expressions such as | label == "examplelabel".

The stage.match block supports a number of stage.* inner blocks, like the top-level block. These are used to construct the nested set of stages to run if the selector matches the labels and content of the log entries. It supports all the same stage.NAME blocks as the in the top level of the loki.process component.

If the specified action is "drop", the metric loki_process_dropped_lines_total is incremented with every line dropped. By default, the reason label is "match_stage", but a custom reason can be provided by using the drop_counter_reason argument.

The following example log lines and stages show how this works.

{ "time":"2023-01-18T17:08:41+00:00", "app":"example1", "component": ["parser","type"], "level" : "WARN", "message" : "app1 log line" }
{ "time":"2023-01-18T17:08:42+00:00", "app":"example2", "component": ["parser","type"], "level" : "ERROR", "message" : "example noisy error" }

stage.json {
    expressions = { "appname" = "app" }
}

stage.labels {
    values = { "applbl" = "appname" }
}

stage.match {
    selector = "{applbl=\"example1\"}"

    stage.json {
        expressions = { "msg" = "message" }
    }
}

stage.match {
    selector = "{applbl=\"qux\"}"
    stage.json {
        expressions = { "msg" = "msg" }
    }
}

stage.match {
    selector = "{applbl=\"example2\"} |~ \".*noisy error.*\""
    action   = "drop"

    drop_counter_reason = "discard_noisy_errors"
}

stage.output {
    source = "msg"
}

The first two stages parse the log lines as JSON, decode the app value into the shared extracted map as appname, and use its value as the applbl label.

The third stage uses the LogQL selector to only execute the nested stages on lines where the applbl="example1". So, for the first line, the nested JSON stage adds msg="app1 log line" into the extracted map.

The fourth stage uses the LogQL selector to only execute on lines where applbl="qux". This means it won’t match any of the input, and the nested JSON stage doesn’t run.

The fifth stage drops entries from lines where applbl is set to ’example2’ and the line contents matches the regex .*noisy error.*. It also increments the loki_process_dropped_lines_total metric with a label drop_counter_reason="discard_noisy_errors".

The final output stage changes the contents of the log line to be the value of msg from the extracted map. In this case, the first log entry’s content is changed to app1 log line.

`stage.metrics`

The stage.metrics inner block configures stage that allows you to define and update metrics based on values from the shared extracted map. The created metrics are available at the Alloy root /metrics endpoint.

The stage.metrics block doesn’t support any arguments and is only configured via a number of nested inner metric.* blocks, one for each metric that should be generated.

The following blocks are supported inside the definition of stage.metrics:

Block	Description	Required
`metric.counter`	Defines a `counter` metric.	no
`metric.gauge`	Defines a `gauge` metric.	no
`metric.histogram`	Defines a `histogram` metric.	no

Note
The metrics will be reset if you reload the Alloy configuration file.

`metric.counter`

Defines a metric whose value only goes up.

The following arguments are supported:

Name	Type	Description	Default	Required
`action`	`string`	The action to take. Valid actions are `inc` and `add`.		yes
`name`	`string`	The metric name.		yes
`count_entry_bytes`	`bool`	If set to true, counts all log lines bytes.	`false`	no
`description`	`string`	The metric’s description and help text.	`""`	no
`match_all`	`bool`	If set to true, all log lines are counted, without attempting to match the `source` to the extracted map.	`false`	no
`max_idle_duration`	`duration`	Maximum amount of time to wait until the metric is marked as ‘stale’ and removed.	`"5m"`	no
`prefix`	`string`	The prefix to the metric name.	`"loki_process_custom_"`	no
`source`	`string`	Key from the extracted data map to use for the metric. Defaults to the metric name.	`""`	no
`value`	`string`	If set, the metric only changes if `source` exactly matches the `value`.	`""`	no

A counter can’t set both match_all to true and a value. A counter can’t set count_entry_bytes without also setting match_all=true or action=add. The valid action values are inc and add. The inc action increases the metric value by 1 for each log line that passed the filter. The add action converts the extracted value to a positive float and adds it to the metric.

`metric.gauge`

Defines a gauge metric whose value can go up or down.

The following arguments are supported:

Name	Type	Description	Default	Required
`action`	`string`	The action to take. Valid actions are `inc`, `dec`, `set`, `add`, or `sub`.		yes
`name`	`string`	The metric name.		yes
`description`	`string`	The metric’s description and help text.	`""`	no
`max_idle_duration`	`duration`	Maximum amount of time to wait until the metric is marked as ‘stale’ and removed.	`"5m"`	no
`prefix`	`string`	The prefix to the metric name.	`"loki_process_custom_"`	no
`source`	`string`	Key from the extracted data map to use for the metric. Defaults to the metric name.	`""`	no
`value`	`string`	If set, the metric only changes if `source` exactly matches the `value`.	`""`	no

The valid action values are inc, dec, set, add, or sub. inc and dec increment and decrement the metric’s value by 1 respectively. If set, add, or sub is chosen, the extracted value must be convertible to a positive float and is set, added to, or subtracted from the metric’s value.

`metric.histogram`

Defines a histogram metric whose values are recorded in predefined buckets.

The following arguments are supported:

Name	Type	Description	Default	Required
`buckets`	`list(float)`	Predefined buckets		yes
`name`	`string`	The metric name.		yes
`description`	`string`	The metric’s description and help text.	`""`	no
`max_idle_duration`	`duration`	Maximum amount of time to wait until the metric is marked as ‘stale’ and removed.	`"5m"`	no
`prefix`	`string`	The prefix to the metric name.	`"loki_process_custom_"`	no
`source`	`string`	Key from the extracted data map to use for the metric. Defaults to the metric name.	`""`	no
`value`	`string`	If set, the metric only changes if `source` exactly matches the `value`.	`""`	no

`metrics` behavior

If value isn’t present, all incoming log entries match.

Label values on created metrics can be dynamic, which can cause exported metrics to explode in cardinality or go stale, for example, when a stream stops receiving new logs. To prevent unbounded growth of the /metrics endpoint, any metrics which haven’t been updated within max_idle_duration are removed. The max_idle_duration must be greater or equal to "1s", and it defaults to "5m".

The metric values extracted from the log data are internally converted to floats. The supported values are the following:

Integer
Floating point number
String - Two types of string format are supported:
- Strings that represent floating point numbers, for example, “0.804” is converted to 0.804.
- Duration format strings. Valid time units are "ns", "us", "ms", "s", "m", "h". A value in this format is converted to a floating point number of seconds, for example, "0.5ms" is converted to 0.0005.
Boolean:
- true is converted to 1.
- false is converted to 0.

The following pipeline creates a counter which increments every time any log line is received by using the match_all parameter. The pipeline creates a second counter which adds the byte size of these log lines by using the count_entry_bytes parameter.

These two metrics disappear after 24 hours if no new entries are received, to avoid building up metrics which no longer serve any use. These two metrics are a good starting point to track the volume of log streams in both the number of entries and their byte size, to identify sources of high-volume or high-cardinality data.

stage.metrics {
    metric.counter {
        name        = "log_lines_total"
        description = "total number of log lines"
        prefix      = "my_custom_tracking_"

        match_all         = true
        action            = "inc"
        max_idle_duration = "24h"
    }
}
stage.metrics {
    metric.counter {
        name        = "log_bytes_total"
        description = "total bytes of log lines"
        prefix      = "my_custom_tracking_"

        match_all         = true
        count_entry_bytes = true
        action            = "add"
        max_idle_duration = "24h"
    }
}

Here, the first stage uses a regular expression to extract text in the format order_status=<string> in the log line. The second stage, defines a counter which increments the successful_orders_total and failed_orders_total based on the previously extracted values.

stage.regex {
    expression = "^.* order_status=(?P<order_status>.*?) .*$"
}
stage.metrics {
    metric.counter {
        name        = "successful_orders_total"
        description = "successful orders"
        source      = "order_status"
        value       = "success"
        action      = "inc"
    }
}
stage.metrics {
    metric.counter {
        name        = "failed_orders_total"
        description = "failed orders"
        source      = "order_status"
        value       = "fail"
        action      = "inc"
    }
}

In this example, the first stage extracts text in the format of retries=<value>, from the log line. The second stage creates a gauge whose current metric value is increased by the number extracted from the retries field.

stage.regex {
    expression = "^.* retries=(?P<retries>\\d+) .*$"
}
stage.metrics {
    metric.gauge {
        name        = "retries_total"
        description = "total_retries"
        source      = "retries"
        action      = "add"
    }
}

The following example shows a histogram that reads response_time from the extracted map and places it into a bucket, both increasing the count of the bucket and the sum for that particular bucket:

stage.metrics {
    metric.histogram {
        name        = "http_response_time_seconds"
        description = "recorded response times"
        source      = "response_time"
        buckets     = [0.001,0.0025,0.005,0.010,0.025,0.050]
    }
}

`stage.multiline`

The stage.multiline inner block merges multiple lines into a single block before passing it on to the next stage in the pipeline.

The following arguments are supported:

Name	Type	Description	Default	Required
`firstline`	`string`	Name from extracted data to use for the log entry.		yes
`max_lines`	`number`	The maximum number of lines a block can have.	`128`	no
`max_wait_time`	`duration`	The maximum time to wait for a multiline block.	`"3s"`	no
`trim_newlines`	`bool`	Whether to trim newlines from the end of each merged entry.	`true`	no

A new block is identified by the RE2 regular expression passed in firstline.

Any line that does not match the expression is considered to be part of the block of the previous match. If no new logs arrive with max_wait_time, the block is sent on. The max_lines field defines the maximum number of lines a block can have. If this is exceeded, a new block is started.

The following example stage and stream of log entries from a Flask web service show how this works.

stage.multiline {
    firstline     = "^\\[\\d{4}-\\d{2}-\\d{2} \\d{1,2}:\\d{2}:\\d{2}\\]"
    max_wait_time = "10s"
}

[2023-01-18 17:41:21] "GET /hello HTTP/1.1" 200 -
[2023-01-18 17:41:25] ERROR in app: Exception on /error [GET]
Traceback (most recent call last):
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 2447, in wsgi_app
    response = self.full_dispatch_request()
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1952, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1821, in handle_user_exception
    reraise(exc_type, exc_value, tb)
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/_compat.py", line 39, in reraise
    raise value
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1950, in full_dispatch_request
    rv = self.dispatch_request()
  File "/home/pallets/.pyenv/versions/3.8.5/lib/python3.8/site-packages/flask/app.py", line 1936, in dispatch_request
    return self.view_functions[rule.endpoint](**req.view_args)
  File "/home/pallets/src/deployment_tools/hello.py", line 10, in error
    raise Exception("Sorry, this route always breaks")
Exception: Sorry, this route always breaks
[2023-01-18 17:42:24] "GET /error HTTP/1.1" 500 -
[2023-01-18 17:42:29] "GET /hello HTTP/1.1" 200 -

All ‘blocks’ that form log entries of separate web requests start with a timestamp in square brackets. The stage detects this with the regular expression in firstline to collapse all lines of the traceback into a single block and thus a single Loki log entry.

`stage.output`

The stage.output inner block configures a processing stage that reads from the extracted map and changes the content of the log entry that’s forwarded to the next component.

The following arguments are supported:

Name	Type	Description	Default	Required
`source`	`string`	Name from extracted data to use for the log entry.		yes

The following example log line and three-stage pipeline shows how this works.

{"user": "John Doe", "message": "hello, world!"}

stage.json {
    expressions = { "user" = "user", "message" = "message" }
}

stage.labels {
    values = { "user" = "user" }
}

stage.output {
    source = "message"
}

The first stage extracts the following key-value pairs into the shared map:

user: John Doe
message: hello, world!

Then, the second stage adds user="John Doe" to the label set of the log entry, and the final output stage changes the log line from the original JSON to hello, world!.

`stage.pack`

The stage.pack inner block configures a transforming stage that replaces the log entry with a JSON object that embeds extracted values and labels with it.

The following arguments are supported:

Name	Type	Description	Default	Required
`labels`	`list(string)`	The values from the extracted data and labels to pack with the log entry.		yes
`ingest_timestamp`	`bool`	Whether to replace the log entry timestamp with the time the `pack` stage runs.	`true`	no

This stage lets you embed extracted values and labels together with the log line, by packing them into a JSON object. The original message is stored under the _entry key, and all other keys retain their values. This is useful in cases where you do want to keep a certain label or metadata, but you don’t want it to be indexed as a label due to high cardinality.

The querying capabilities of Loki make it easy to still access this data so it can be filtered and aggregated at query time.

For example, consider the following log entry:

log_line: "something went wrong"
labels:   { "level" = "error", "env" = "dev", "user_id" = "f8fas0r" }

and this processing stage:

stage.pack {
    labels = ["env", "user_id"]
}

The stage transforms the log entry into the following JSON object, where the two embedded labels are removed from the original log entry:

{
  "_entry": "something went wrong",
  "env": "dev",
  "user_id": "f8fas0r"
}

At query time, the Loki unpack parser can be used to access these embedded labels and replace the log line with the original one stored in the _entry field automatically.

When combining several log streams to use with the pack stage, you can set ingest_timestamp to true to avoid interlaced timestamps and out-of-order ingestion issues.

`stage.pattern`

The stage.pattern inner block configures a processing stage that parses log lines using LogQL pattern expressions and uses named captures to add data into the shared extracted map of values.

The following arguments are supported:

Name	Type	Description	Default	Required
`pattern`	`string`	A valid LogQL pattern expression. At least one capture must be named.		yes
`source`	`string`	Name from extracted data to parse. If empty, uses the log message.	`""`	no
`labels_from_groups`	`bool`	Whether to automatically add named capture groups as labels.	`false`	no

The pattern field needs to be a LogQL pattern expression. Every matched capture is added to the extracted map. The name of the capture is used as the key in the extracted map for the matched value.

When labels_from_groups is set to true, any named captures from the pattern expression are automatically added as labels in addition to being added to the extracted map. If a capture group name matches an existing label name, the existing label’s value will be overridden by the extracted value.

If the source is empty or missing, then the stage parses the log line itself. If the source set, the stage parses a previously extracted value with the same name.

Given the following log line and pattern stage, the extracted values are shown below:

2019-01-01T01:00:00.000000001Z stderr P i'm a log message!

stage.pattern {
    pattern = "<time> <stream> <flags> <content>"
}

time: 2019-01-01T01:00:00.000000001Z,
stream: stderr,
flags: P,
content: i'm a log message

If the source value is set, then the pattern expression is applied to the value stored in the shared map under that name.

The following log line is put through this two-stage pipeline:

{"timestamp":"2022-01-01T01:00:00.000000001Z"}

stage.json {
    expressions = { time = "timestamp" }
}
stage.pattern {
    pattern = "<year>-<month>-<day>T<hour>:<minute>:<second>.<nano>Z"
    source  = "time"
}

The first stage adds the following key-value pair into the extracted map:

time: 2022-01-01T01:00:00.000000001Z

Then, the pattern stage parses the value for time from the shared values and appends the subsequent key-value pair back into the extracted values map:

time: 2022-01-01T01:00:00.000000001Z
year: 2022
month: 01
day: 01
hour: 01
minute: 00
second: 00
nano: 000000001

The following example demonstrates how labels_from_groups can automatically add the matched groups as labels:

{"timestamp":"2022-01-01T01:00:00.000000001Z"}

stage.json {
    expressions = { time = "timestamp" }
}
stage.pattern {
    pattern            = "<year>-<month>-<day>T<hour>:<minute>:<second>.<nano>Z"
    source             = "time"
    labels_from_groups = true   // Sets up a label for each field parsed from the pattern
}

This pipeline produces the same extracted values as before in addition to adding labels to the entry:

time: 2022-01-01T01:00:00.000000001Z
year: 2022
month: 01
day: 01
hour: 01
minute: 00
second: 00
nano: 000000001

`stage.regex`

The stage.regex inner block configures a processing stage that parses log lines using regular expressions and uses named capture groups for adding data into the shared extracted map of values.

The following arguments are supported:

Name	Type	Description	Default	Required
`expression`	`string`	A valid RE2 regular expression. Each capture group must be named.		yes
`source`	`string`	Name from extracted data to parse. If empty, uses the log message.	`""`	no
`labels_from_groups`	`bool`	Whether to automatically add named capture groups as labels.	`false`	no

The expression field needs to be a RE2 regular expression string. Every matched capture group is added to the extracted map, so it must be named like: (?P<name>re). The name of the capture group is then used as the key in the extracted map for the matched value.

Because of how Alloy syntax strings work, any backslashes in expression must be escaped with a double backslash, for example, "\\w" or "\\S+".

When labels_from_groups is set to true, any named capture groups from the regex expression are automatically added as labels in addition to being added to the extracted map. If a capture group name matches an existing label name, the existing label’s value will be overridden by the extracted value.

If the source is empty or missing, then the stage parses the log line itself. If the source is set, the stage parses a previously extracted value with the same name.

Given the following log line and regular expression stage, the extracted values are shown below:

2019-01-01T01:00:00.000000001Z stderr P i'm a log message!

stage.regex {
    expression = "^(?s)(?P<time>\\S+?) (?P<stream>stdout|stderr) (?P<flags>\\S+?) (?P<content>.*)$"
}

time: 2019-01-01T01:00:00.000000001Z,
stream: stderr,
flags: P,
content: i'm a log message

If the source value is set, then the regular expression is applied to the value stored in the shared map under that name.

The following log line is put through this two-stage pipeline:

{"timestamp":"2022-01-01T01:00:00.000000001Z"}

stage.json {
    expressions = { time = "timestamp" }
}
stage.regex {
    expression = "^(?P<year>\\d+)"
    source     = "time"
}

The first stage adds the following key-value pair into the extracted map:

time: 2022-01-01T01:00:00.000000001Z

Then, the regular expression stage parses the value for time from the shared values and appends the subsequent key-value pair back into the extracted values map:

year: 2022

The following example demonstrates how labels_from_groups can automatically add the matched groups as labels:

{"timestamp":"2022-01-01T01:00:00.000000001Z"}

stage.json {
    expressions = { time = "timestamp" }
}
stage.regex {
    expression = "^(?P<year>\\d+)"
    source = "time"
    labels_from_groups = true   // Sets up an 'year' label, based on the 'year' capture group's value.
}

This pipeline produces the same extracted values as before:

time: 2022-01-01T01:00:00.000000001Z
year: 2022

`stage.replace`

The stage.replace inner block configures a stage that parses a log line using a regular expression and replaces the log line contents. Named capture groups in the regular expression also support adding data into the shared extracted map.

The following arguments are supported:

Name	Type	Description	Required
`expression`	`string`	A RE2 regular expression containing capture groups.	yes
`replace`	`string`	Value replaced by the capture group.	no
`source`	`string`	Source of the data to parse. If empty, it uses the log message.	no

Each capture group and named capture group in expression is replaced with the value given in replace.

expression must contain valid RE2 regular expression capture groups. You can also name some groups using syntax such as (?P<name>re). If any of the capture groups are named, their values will be set into the shared extracted map under the name of the regular expression group.

The source field defines the source of data to parse using expression. When source is missing or empty, the stage parses the log line itself, but it can also be used to parse a previously extracted value. The replaced value is assigned back to the source key.

Because of how Alloy syntax treats backslashes in double-quoted strings, all backslashes in a regular expression must be escaped like "\\w*".

The following log line and stage shows how this works. Since source is omitted, the replacement occurs on the log line itself.

2023-01-01T01:00:00.000000001Z stderr P i'm a log message who has sensitive information with password xyz!

stage.replace {
    expression = "password (\\S+)"
    replace    = "*****"
}

The log line is transformed to

2023-01-01T01:00:00.000000001Z stderr P i'm a log message who has sensitive information with password *****!

If replace is empty, then the captured value is omitted instead.

In the following example, source is defined.

{"time":"2023-01-01T01:00:00.000000001Z", "level": "info", "msg":"11.11.11.11 - \"POST /loki/api/push/ HTTP/1.1\" 200 932 \"-\" \"Mozilla/5.0\"}

stage.json {
    expressions = { "level" = "", "msg" = "" }
}

stage.replace {
    expression = "\\S+ - \"POST (\\S+) .*"
    source     = "msg"
    replace    = "redacted_url"
}

The JSON stage adds the following key-value pairs into the extracted map:

time: 2023-01-01T01:00:00.000000001Z
level: info
msg: "11.11.11.11 - "POST /loki/api/push/ HTTP/1.1" 200 932 "-" "Mozilla/5.0"

The replace stage acts on the msg value. The capture group matches against /loki/api/push and is replaced by redacted_url.

The msg value is finally transformed into:

msg: "11.11.11.11 - "POST redacted_url HTTP/1.1" 200 932 "-" "Mozilla/5.0"

The replace field can use a set of templating functions, by utilizing Go’s text/template package.

The following example shows how this works with named capture groups with a sample log line and stage.

11.11.11.11 - alloy [01/Jan/2023:00:00:01 +0200]

stage.replace {
    expression = "^(?P<ip>\\S+) (?P<identd>\\S+) (?P<user>\\S+) \\[(?P<timestamp>[\\w:/]+\\s[+\\-]\\d{4})\\]"
    replace    = "{{ .Value | ToUpper }}"
}

Since source is empty, the regular expression parses the log line itself and extracts the named capture groups to the shared map of values. The replace field acts on these extracted values and converts them to uppercase:

ip: 11.11.11.11
identd: -
user: FRANK
timestamp: 01/JAN/2023:00:00:01 +0200

and the log line becomes:

11.11.11.11 - FRANK [01/JAN/2023:00:00:01 +0200]

The following list contains available functions with examples of more complex replace fields.

ToLower, ToUpper, Replace, Trim, TrimLeftTrimRight, TrimPrefix, TrimSuffix, TrimSpace, Hash, Sha2Hash, regexReplaceAll, regexReplaceAllLiteral

| "{{ if eq .Value \"200\" }}{{ Replace .Value \"200\" \"HttpStatusOk\" -1 }}{{ else }}{{ .Value | ToUpper }}{{ end }}" |
| "*IP4*{{ .Value                                                                                | Hash "salt" }}*"     |

`stage.sampling`

The sampling stage is used to sample the logs. Configuring the value rate = 0.1 means that 10% of the logs continue to be processed. The remaining 90% of the logs are dropped.

The following arguments are supported:

Name	Type	Description	Default	Required
`rate`	`float`	The sampling rate in a range of `[0, 1]`		yes
`drop_counter_reason`	`string`	The label to add to `loki_process_dropped_lines_total` metric when logs are dropped by this stage.	`sampling_stage`	no

For example, the configuration below will sample 25% of the logs and drop the remaining 75%. When logs are dropped, the loki_process_dropped_lines_total metric is incremented with an additional reason=logs_sampling label.

stage.sampling {
    rate = 0.25
    drop_counter_reason = "logs_sampling"
}

`stage.static_labels`

The stage.static_labels inner block configures a static_labels processing stage that adds a static set of labels to incoming log entries.

For labels that are dynamic, refer to [stage.labels][stage.labels]

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`map(string)`	Configures a `static_labels` processing stage.	`{}`	no

stage.static_labels {
    values = {
      foo = "fooval",
      bar = "barval",
    }
}

`stage.structured_metadata`

The stage.structured_metadata inner block configures a stage that can read data from the extracted values map and add them to log entries as structured metadata. If you add labels to structured metadata, the labels are removed from the label map.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`map(string)`	Specifies the list of labels to add from extracted values map to log entry.	`{}`	no
`regex`	`string`	Specifies a regular expression, matching extracted values are added to structured metadata.	`""`	no

In a structured_metadata stage, the keys for the values map define the labels to set and the values define how to look them up. If the value is empty, it’s inferred to be the same as the key.

stage.structured_metadata {
    values = {
      env  = "",         // Sets up an 'env' property to structured metadata, based on the 'env' extracted value.
      user = "username", // Sets up a 'user' property to structured metadata, based on the 'username' extracted value.
    }
    regex = "pod_.*"   // Adds all extracted values starting with 'pod_' to structured metadata.
}

`stage.structured_metadata_drop`

The stage.structured_metadata_drop inner block configures a processing stage that drops structured metadata from incoming log entries.

The following arguments are supported:

Name	Type	Description	Default	Required
`values`	`list(string)`	Configures a `structured_metadata_drop` processing stage.	`[]`

stage.structured_metadata_drop {
    values = [ "kubernetes_node_name", "kubernetes_namespace" ]
}

`stage.template`

The stage.template inner block configures a transforming stage that allows users to manipulate the values in the extracted map by using Go’s text/template package syntax. This stage is primarily useful for manipulating and standardizing data from previous stages before setting them as labels in a subsequent stage. Example use cases are replacing spaces with underscores, converting uppercase strings to lowercase, or hashing a value.

The template stage can also create new keys in the extracted map.

The following arguments are supported:

Name	Type	Description	Default	Required
`source`	`string`	Name from extracted data to parse. If the key doesn’t exist, a new entry is created.		yes
`template`	`string`	Go template string to use.		yes

The template string can be any valid template that can be used by Go’s text/template. It supports all functions from the sprig package, as well as the following list of custom functions:

ToLower, ToUpper, Replace, Trim, TrimLeftTrimRight, TrimPrefix, TrimSuffix, TrimSpace, Hash, Sha2Hash, regexReplaceAll, regexReplaceAllLiteral

More details on each of these functions can be found in the supported functions section.

Assuming no data is present on the extracted map, the following stage simply adds the new_key: "hello_world" key-value pair to the shared map.

stage.template {
    source   = "new_key"
    template = "hello_world"
}

If the source value exists in the extract fields, its value can be referred to as .Value in the template. The next stage takes the current value of app from the extracted map, converts it to lowercase, and adds a suffix to its value:

stage.template {
    source   = "app"
    template = "{{ ToLower .Value }}_some_suffix"
}

Any previously extracted keys are available for template to expand and use. The next stage takes the current values for level, app and module and creates a new key named output_message:

stage.template {
    source   = "output_msg"
    template = "{{ .level }} for app {{ ToUpper .app }} in module {{.module}}"
}

A special key named Entry can be used to reference the current line. This can be useful when you need to append/prepend something to the log line, like this snippet:

stage.template {
    source   = "message"
    template = "{{.app }}: {{ .Entry }}"
}
stage.output {
    source = "message"
}

Supported functions

In addition to supporting all functions from the sprig package, the template stage supports the following custom functions.

`ToLower` and `ToUpper`

ToLower and ToUpper convert the entire string to lowercase and uppercase, respectively.

The following example shows how you can use this function.

stage.template {
    source   = "out"
    template = "{{ ToLower .app }}"
}
stage.template {
    source   = "out"
    template = "{{ .app | ToUpper }}"
}

`Replace`

The Replace function syntax is defined as {{ Replace <string> <old> <new> <n> }}.

The function returns a copy of the input string, with instances of the <old> argument being replaced by <new>. The function replaces up to <n> non-overlapping instances of the second argument. If <n> is less than zero, there is no limit on the number of replacements. Finally, if <old> is empty, it matches before and after every UTF-8 character in the string.

This example replaces the first two instances of the loki word by Loki:

stage.template {
    source   = "output"
    template = `{{ Replace .Value "loki" "Loki" 2 }}`
}

`Trim`, `TrimLeft`, `TrimRight`, `TrimSpace`, `TrimPrefix`, `TrimSuffix`

Trim returns a slice of the string s with all leading and trailing Unicode code points contained in cutset removed.
TrimLeft and TrimRight are the same as Trim except that they trim only leading and trailing characters, respectively.
TrimSpace returns a slice of the string s, with all leading and trailing white space removed, as defined by Unicode.
TrimPrefix and TrimSuffix trim the supplied prefix or suffix, respectively.

The following example shows how you can use this function.

stage.template {
    source   = "output"
    template = `{{ Trim .Value ",. " }}`
}
stage.template {
    source   = "output"
    template = "{{ TrimSpace .Value }}"
}
stage.template {
    source   = "output"
    template = `{{ TrimPrefix .Value "--" }}`
}

`regexReplaceAll` and `regexReplaceAllLiteral`

regexReplaceAll returns a copy of the input string, replacing matches of the Regexp with the replacement string. Inside the replacement string, $ characters are interpreted as in Expand functions. For example, $1 represents the first captured submatch.

regexReplaceAllLiteral returns a copy of the input string, replacing matches of the Regexp with the replacement string. The replacement string is substituted directly, without using Expand.

stage.template {
    source   = "output"
    template = `{{ regexReplaceAll "(a*)bc" .Value "${1}a" }}`
}
stage.template {
    source   = "output"
    template = `{{ regexReplaceAllLiteral "(ts=)" .Value "timestamp=" }}`
}

`Hash` and `Sha2Hash`

Hash returns a Sha3_256 hash of the string, represented as a hexadecimal number of 64 digits. You can use it to obfuscate sensitive data and PII in the logs. It requires a (fixed) salt value, to add complexity to low input domains, for example, all possible social security numbers. Sha2Hash returns a Sha2_256 of the string which is faster and less CPU-intensive than Hash, however it’s less secure.

The following example shows how you can use this function.

stage.template {
    source   = "output"
    template = `{{ Hash .Value "salt" }}`
}
stage.template {
    source   = "output"
    template = `{{ Sha2Hash .Value "salt" }}`
}

We recommend using Hash as it has a stronger hashing algorithm.

`stage.tenant`

The stage.tenant inner block sets the tenant ID for the log entry by obtaining it from a field in the extracted data map, a label, or a provided value.

The following arguments are supported:

Name	Type	Description	Default	Required
`label`	`string`	The label to set as tenant ID.	`""`	no
`source`	`string`	The name from the extracted value to use as tenant ID.	`""`	no
`value`	`string`	The value to set as the tenant ID.	`""`	no

The block expects only one of label, source or value to be provided.

The following stage assigns the fixed value team-a as the tenant ID:

stage.tenant {
    value = "team-a"
}

This stage extracts the tenant ID from the customer_id field after parsing the log entry as JSON in the shared extracted map:

stage.json {
    expressions = { "customer_id" = "" }
}
stage.tenant {
    source = "customer_id"
}

The final example extracts the tenant ID from a label set by a previous stage:

stage.labels {
  values = {
    "namespace" = "k8s_namespace",
  }
}

stage.tenant {
    label = "namespace"
}

`stage.timestamp`

The stage.timestamp inner block configures a processing stage that sets the timestamp of log entries before they’re forwarded to the next component. When no timestamp stage is set, the log entry timestamp defaults to the time when the log entry was scraped.

The following arguments are supported:

Name	Type	Description	Default	Required
`format`	`string`	Determines how to parse the source string.		yes
`source`	`string`	Name from extracted values map to use for the timestamp.		yes
`action_on_failure`	`string`	What to do when the timestamp can’t be extracted or parsed.	`"fudge"`	no
`fallback_formats`	`list(string)`	Fallback formats to try if the `format` field fails.	`[]`	no
`location`	`string`	IANA Timezone Database location to use when parsing.	`""`	no

Note
Be careful with further stages which may also override the timestamp. For example, a stage.pack with ingest_timestamp set to true could replace the timestamp which stage.timestamp had set earlier in the pipeline.

The source field defines which value from the shared map of extracted values the stage should attempt to parse as a timestamp.

The format field defines how that source should be parsed.

The format can be set to one of the following shorthand values for commonly used forms:

ANSIC: Mon Jan _2 15:04:05 2006
UnixDate: Mon Jan _2 15:04:05 MST 2006
RubyDate: Mon Jan 02 15:04:05 -0700 2006
RFC822: 02 Jan 06 15:04 MST
RFC822Z: 02 Jan 06 15:04 -0700
RFC850: Monday, 02-Jan-06 15:04:05 MST
RFC1123: Mon, 02 Jan 2006 15:04:05 MST
RFC1123Z: Mon, 02 Jan 2006 15:04:05 -0700
RFC3339: 2006-01-02T15:04:05-07:00
RFC3339Nano: 2006-01-02T15:04:05.999999999-07:00

Additionally, support for common Unix timestamps is supported with the following format values:

Unix: 1562708916 or with fractions 1562708916.000000123
UnixMs: 1562708916414
UnixUs: 1562708916414123
UnixNs: 1562708916000000123

Otherwise, the field accepts a custom format string that defines how an arbitrary reference point in history should be interpreted by the stage. The arbitrary reference point is Mon Jan 2 15:04:05 -0700 MST 2006.

The string value of the field is passed directly to the layout parameter in Go’s time.Parse function.

If the custom format has no year component, the stage uses the current year, according to the system’s clock.

The following table shows the supported reference values to use when defining a custom format.

Timestamp Component	Format value
Year	06, 2006
Month	1, 01, Jan, January
Day	2, 02, _2 (two digits right justified)
Day of the week	Mon, Monday
Hour	3 (12-hour), 03 (12-hour zero prefixed), 15 (24-hour)
Minute	4, 04
Second	5, 05
Fraction of second	.000 (ms zero prefixed), .000000 (μs), .000000000 (ns), .999 (ms without trailing zeroes), .999999 (μs), .999999999 (ns)
12-hour period	pm, PM
Timezone name	MST
Timezone offset	-0700, -070000 (with seconds), -07, -07:00, -07:00:00 (with seconds)
Timezone ISO-8601	Z0700 (Z for UTC or time offset), Z070000, Z07, Z07:00, Z07:00:00

Note
If you define a custom timestamp, the format value for each timestamp component must be one of the values specified in the table above. For example, to indicate the year, the format value must be 06 or 2006 and not any other value like 23 or 2023.

The fallback_formats field defines one or more format fields to try and parse the timestamp with, if parsing with format fails.

The location field must be a valid IANA Timezone Database location and determines in which timezone the timestamp value is interpreted to be in.

The action_on_failure field defines what should happen when the source field doesn’t exist in the shared extracted map, or if the timestamp parsing fails.

The supported actions are:

fudge (default): Change the timestamp to the last known timestamp, summing up 1 nanosecond to guarantee log entries ordering.
skip: Don’t change the timestamp and keep the time when the log entry was scraped.

The following stage fetches the time value from the shared values map, parses it as a RFC3339 format, and sets it as the log entry’s timestamp.

stage.timestamp {
    source = "time"
    format = "RFC3339"
}

The following example would parse a timestamp such as 2024-12-20T09:14:58,381+02:00:

stage.timestamp {
    source = "time"
    format = "2006-01-02T15:04:05,000-07:00"
}

`stage.truncate`

The stage.truncate inner block configures a processing stage that truncates log entries, labels, extracted map fields, or structured metadata that exceed configured limits.

The stage.truncate block doesn’t support any arguments and is only configured via a number of nested inner rule blocks.

The following block is supported inside the definition of stage.truncate:

Block	Description	Required
`rule`	Defines a truncation rule.	yes

`rule`

Defines a truncation rule that will apply to the log line, labels, structured metadata, or extracted map.

The following arguments are supported:

Name	Type	Description	Default	Required
`limit`	`string`	Maximum length before truncating.	`""`	yes
`sources`	`list(string)`	Sources of the data to truncate. If empty, will truncate all.	`""`	no
`source_type`	`string`	Source location of the data to truncate.	`"line"`	no
`suffix`	`string`	Suffix to append to truncated values.	``	no

The limit attribute should be expressed in logical units, for example "1KiB". The stage checks the byte length of the log line, label values, or structured metadata values against the configured limit and truncates if it exceeds the limit. If you provide a suffix, the limit is reduced by the length of the suffix, and the suffix is appended to the truncated value.

The source_type attribute must be one of "line", "label", "structured_metadata", or "extracted". If the source attribute is specified, the stage will only truncate a label, structured metadata, or extracted field of the same name. If source is empty, all labels, structured metadata, or extracted fields will be truncated if they exceed the limit.

Whenever a line, label, extracted field, or structured metadata value is truncated, the metric loki_process_truncated_fields_total is incremented. The field label will either be line, label, extracted, or structured_metadata.

If anything has been truncated, the extracted map for the entry contains a "truncated" field with a comma delimited list of field types that have been truncated.

Example

loki.process "default" {
  forward_to = [loki.write.default.receiver]
  stage.truncate {
    rule {
      limit = "12B"
      suffix = "..."
    }

    rule {
      limit = "12B"
      suffix = "..."
      source_type = "label"
    }
  }
}

Given the following input entry, the first rule in the stage truncates the entry "I'm a log message!" into "I'm a log...". The second rule truncates the "label2" label’s value "hello world" to "hello...".

entry: "I'm a log message!"
labels: { "label1": "hi", "label2": "hello world" }
structured_metadata: { "metadata1": "here is some metadata", "metadata2": "and here is some more"}

The extracted map for the entry contains the "truncated" field. You can use this entry to add a label in stage.labels or structured metadata in stage.structured_metadata to the entry so you can identify the logs as truncated after processing.

truncated: label,line

`stage.windowsevent`

The windowsevent stage extracts data from the message string in the Windows Event Log.

The following arguments are supported:

Name	Type	Description	Default	Required
`source`	`string`	Name of the field in the extracted data to parse.	`message`	no
`drop_invalid_labels`	`bool`	Whether to drop fields that aren’t valid label names.	`false`	no
`overwrite_existing`	`bool`	Whether to overwrite existing extracted data fields.	`false`	no

When overwrite_existing is set to true, the stage overwrites existing extracted data fields with the same name. If set to false, the _extracted suffix is appended to an existing field name.

When drop_invalid_labels is set to true, the stage drops fields that aren’t valid label names. If set to false, the stage automatically converts them into valid labels, replacing invalid characters with underscores.

The windowsevent stage expects the message to be structured in sections that are split by empty lines.

The first section of the input is treated as a whole block and stored in the extracted map with the key Description.

Sections following the Description are expected to contain key-value pairs in the format key:value.

If the first line of a section has no value, for example “Subject:”, the key acts as a prefix for subsequent keys in the same section.

If a line within a section doesn’t include the : symbol, it’s considered part of the previous entry’s value. The line is appended to the previous value, separated by a comma.

Lines in a section without a preceding valid entry (key-value pair) are ignored and discarded.

Example with `loki.source.windowsevent`

loki.source.windowsevent "security"  {
    eventlog_name = "Security"
    forward_to = [loki.process.default.receiver]
}
loki.process "default" {
  forward_to = [loki.write.default.receiver]
  stage.json {
      expressions = {
          message = "",
          Overwritten = "",
      }
  }
  stage.windowsevent {
      source = "message"
      overwrite_existing = true
  }
  stage.labels {
    values = {
      Description = "",
      Subject_SecurityID  = "",        
      ReadOP = "Subject_ReadOperation",
    }
  }
}

The loki.source.windowsevent component forwards Windows security events to the loki.process component.

Given the following event:

{"event_id": 1, "Overwritten": "old", "message": ""Special privileges assigned to new logon.\r\n\r\nSubject:\r\n\tSecurity ID:\t\tS-1-1-1\r\n\tAccount Name:\t\tSYSTEM\r\n\tAccount Domain:\t\tNT AUTHORITY\r\n\tLogon ID:\t\t0xAAA\r\n\r\nPrivileges:\t\tSeAssignPrimaryTokenPrivilege\r\n\t\t\tSeTcbPrivilege\r\n\t\t\tSeSecurityPrivilege\r\n\t\t\tSeTakeOwnershipPrivilege\r\n\t\t\tSeLoadDriverPrivilege\r\n\t\t\tSeBackupPrivilege\r\n\t\t\tSeRestorePrivilege\r\n\t\t\tSeDebugPrivilege\r\n\t\t\tSeAuditPrivilege\r\n\t\t\tSeSystemEnvironmentPrivilege\r\n\t\t\tSeImpersonatePrivilege\r\n\t\t\tSeDelegateSessionUserImpersonatePrivilege""}

The json stage would create the following key-value pairs in the set of extracted data:

message: "Special privileges assigned to new logon.\r\n\r\nSubject:\r\n\tSecurity ID:\t\tS-1-1-1\r\n\tAccount Name:\t\tSYSTEM\r\n\tAccount Domain:\t\tNT AUTHORITY\r\n\tLogon ID:\t\t0xAAA\r\n\r\nPrivileges:\t\tSeAssignPrimaryTokenPrivilege\r\n\t\t\tSeTcbPrivilege\r\n\t\t\tSeSecurityPrivilege"
Overwritten: old

The windowsevent stage parses the value of message from the extracted data and appends or overwrites the following key-value pairs to the set of extracted data:

Description: “Special privileges assigned to new logon.”,
Subject_SecurityID: “S-1-1-1”,
Subject_AccountName: “SYSTEM”,
Subject_AccountDomain: “NT AUTHORITY”,
Subject_LogonID: “0xAAA”,
Privileges: “SeAssignPrimaryTokenPrivilege,SeTcbPrivilege,SeSecurityPrivilege”,

Finally the labels stage uses the extracted values Description, Subject_SecurityID and Subject_ReadOperation to add them as labels of the log entry before forwarding it to a loki.write component.

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`receiver`	`LogsReceiver`	A value that other components can use to send log entries to.

Component health

loki.process is only reported as unhealthy if given an invalid configuration.

Debug information

loki.process doesn’t expose any component-specific debug information.

Debug metrics

loki_process_dropped_lines_total (counter): Number of lines dropped as part of a processing stage.
loki_process_dropped_lines_by_label_total (counter): Number of lines dropped when by_label_name is non-empty in [stage.limit][].
loki_process_truncated_fields_total (counter): Number of lines, label values, extracted field values, and structured metadata values truncated as part of a truncate stage.
loki_process_cri_partial_lines_flushed_total (counter): Number of partial lines flushed prematurely due to max_partial_lines limit being exceeded in [stage.cri][].
loki_process_cri_lines_truncated_total (counter): Number of lines truncated due to max_partial_line_size limit in [stage.cri][].

Example

This example creates a loki.process component that extracts the environment value from a JSON log line and sets it as a label named ’env’.

loki.process "local" {
  forward_to = [loki.write.onprem.receiver]

  stage.json {
      expressions = { "extracted_env" = "environment" }
  }

  stage.labels {
      values = { "env" = "extracted_env" }
  }
}

Compatible components

loki.process can accept arguments from the following components:

Components that export Loki LogsReceiver

loki.process has exports that can be consumed by the following components:

Components that consume Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.relabel

Mon, 13 Apr 2026 07:37:47 +0000

`loki.relabel`

The loki.relabel component rewrites the label set of each log entry passed to its receiver by applying one or more relabeling rules and forwards the results to the list of receivers in the component’s arguments.

If no labels remain after the relabeling rules are applied, then the log entries are dropped.

The most common use of loki.relabel is to filter log entries or standardize the label set that’s passed to one or more downstream receivers. The rule blocks are applied to the label set of each log entry in order of their appearance in the configuration file. The configured rules can be retrieved by calling the function in the rules export field.

If you’re looking for a way to process the log entry contents, use the loki.process component instead.

You can specify multiple loki.relabel components by giving them different labels.

Usage

loki.relabel "<LABEL>" {
  forward_to = <RECEIVER_LIST>

  rule {
    ...
  }

  ...
}

Arguments

You can use the following arguments with loki.relabel:

Name	Type	Description	Default	Required
`forward_to`	`list(receiver)`	Where to forward log entries after relabeling.		yes
`max_cache_size`	`int`	The maximum number of elements to hold in the relabeling cache	`10000`	no

Blocks

You can use the following block with loki.relabel:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`rule`

The rule block contains the definition of any relabeling rules that can be applied to an input log. The transformations are applied in top-down order if more than one rule block is defined.

You can use the following arguments to configure a rule. All arguments are optional. Omitted fields take their default values.

Name	Type	Description	Default	Required
`action`	`string`	The relabeling action to perform.	replace	no
`modulus`	`uint`	A positive integer used to calculate the modulus of the hashed source label values.		no
`regex`	`string`	A valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the `source_label` and `separator` fields or filter labels during the `labelkeep/labeldrop/labelmap` actions.	`(.*)`	no
`replacement`	`string`	The value against which a regular expression replace is performed if the regular expression matches the extracted value. Supports previously captured groups.	`"$1"`	no
`separator`	`string`	The separator used to concatenate the values present in `source_labels`.	;	no
`source_labels`	`list(string)`	The list of labels whose values are to be selected. Their content is concatenated using the `separator` and matched against `regex`.		no
`target_label`	`string`	Label to which the resulting value is written to.		no

You can use the following actions:

drop - Drops logs where regex matches the string extracted using the source_labels and separator.
dropequal - Drop targets for which the concatenated source_labels do match target_label.
hashmod - Hashes the concatenated labels, calculates its modulo modulus, and writes the result to the target_label.
keep - Keeps logs where regex matches the string extracted using the source_labels and separator.
keepequal - Drop targets for which the concatenated source_labels don’t match target_label.
labeldrop - Matches regex against all label names. Any labels that match are removed from the log’s label set.
labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the log’s label set.
labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
uppercase - Sets target_label to the uppercase form of the concatenated source_labels.

Note
The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`receiver`	`receiver`	The input receiver where log lines are sent to be relabeled.
`rules`	`RelabelRules`	The currently configured relabeling rules.

Component health

loki.relabel is only reported as unhealthy if given an invalid configuration. In those cases, exported fields are kept at their last healthy values.

Debug information

loki.relabel doesn’t expose any component-specific debug information.

Debug metrics

loki_relabel_entries_processed (counter): Total number of log entries processed.
loki_relabel_entries_written (counter): Total number of log entries forwarded.
loki_relabel_cache_misses (counter): Total number of cache misses.
loki_relabel_cache_hits (counter): Total number of cache hits.
loki_relabel_cache_size (gauge): Total size of relabel cache.

Example

The following example creates a loki.relabel component that only forwards entries whose ’level’ value is set to ’error'.

loki.relabel "keep_error_only" {
  forward_to = [loki.write.onprem.receiver]

  rule {
    action        = "keep"
    source_labels = ["level"]
    regex         = "error"
  }
}

Compatible components

loki.relabel can accept arguments from the following components:

Components that export Loki LogsReceiver

loki.relabel has exports that can be consumed by the following components:

Components that consume Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.rules.kubernetes

Mon, 13 Apr 2026 07:37:47 +0000

`loki.rules.kubernetes`

loki.rules.kubernetes discovers PrometheusRule Kubernetes resources and loads them into a Loki instance.

You can specify multiple loki.rules.kubernetes components by giving them different labels.
Kubernetes label selectors can be used to limit the Namespace and PrometheusRule resources considered during reconciliation.
Compatible with the Ruler APIs of Grafana Loki, Grafana Cloud, and Grafana Enterprise Metrics.
Compatible with the PrometheusRule CRD from the prometheus-operator.
This component accesses the Kubernetes REST API from within a Pod.

Note
This component requires Role-based access control (RBAC) to be set up in Kubernetes for Alloy to access it via the Kubernetes REST API.

Usage

loki.rules.kubernetes "<LABEL>" {
  address = "<LOKI_RULER_URL>"
}

Arguments

You can use the following arguments with loki.rules.kubernetes:

Name	Type	Description	Default	Required
`address`	`string`	URL of the Loki ruler.		yes
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`loki_namespace_prefix`	`string`	Prefix used to differentiate multiple Alloy deployments.	`"alloy"`	no
`proxy_url`	`string`	HTTP proxy to proxy requests through.		no
`sync_interval`	`duration`	Amount of time between reconciliations with Loki.	`"30s"`	no
`tenant_id`	`string`	Loki tenant ID.		no
`use_legacy_routes`	`bool`	Whether to use deprecated ruler API endpoints.	`false`	no

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
bearer_token_file argument
bearer_token argument
[oauth2][oauth2] block

If no tenant_id is provided, the component assumes that the Loki instance at address is running in single-tenant mode and no X-Scope-OrgID header is sent.

The sync_interval argument determines how often the Loki ruler API is accessed to reload the current state. Interaction with the Kubernetes API works differently. Updates are processed as events from the Kubernetes API server according to the informer pattern.

You can use the loki_namespace_prefix argument to separate the rules managed by multiple Alloy deployments across your infrastructure. You should set the prefix to a unique value for each deployment.

Blocks

You can use the following blocks with loki.rules.kubernetes:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`authorization`

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`extra_query_matchers`

The extra_query_matchers block has no attributes. It contains zero or more [matcher][] blocks. These blocks allow you to add extra label matchers to all queries that are discovered by the loki.rules.kubernetes component. The algorithm for adding the label matchers to queries is the same as the one used by the promtool promql label-matchers set command. It’s adapted to work with the LogQL parser.

`matcher`

The matcher block describes a label matcher that’s added to each query found in PrometheusRule CRDs.

The following arguments are supported:

Name	Type	Description	Required
`match_type`	`string`	The type of match. One of `=`, `!=`, `=~` or `!~`.	yes
`name`	`string`	Name of the label to match.	yes
`value`	`string`	Value of the label to match.	yes

`rule_selector` and `rule_namespace_selector`

The rule_selector and rule_namespace_selector blocks describe a Kubernetes label selector for rule or namespace discovery.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	yes

When the match_labels argument is empty, all resources are matched.

`match_expression`

The match_expression block describes a Kubernetes label match expression for rule or namespace discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`list(string)`	The values used when matching.	no

The operator argument should be one of the following strings:

"in"
"notin"
"exists"

`oauth2`

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_from_environment uses the environment variables HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or the lowercase versions thereof). Requests use the proxy from the environment variable matching their scheme, unless excluded by NO_PROXY. proxy_url and no_proxy must not be configured if proxy_from_environment is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

When min_version isn’t provided, the minimum acceptable TLS version is inherited from Go’s default minimum version, TLS 1.2. If min_version is provided, it must be set to one of the following strings:

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

loki.rules.kubernetes doesn’t export any fields.

Component health

loki.rules.kubernetes is reported as unhealthy if given an invalid configuration or an error occurs during reconciliation.

Debug information

loki.rules.kubernetes exposes resource-level debug information.

The following are exposed per discovered PrometheusRule resource:

The Kubernetes namespace.
The resource name.
The resource UID.
The number of rule groups.

The following are exposed per discovered Loki rule namespace resource:

The namespace name.
The number of rule groups.

Only resources managed by the component are exposed - regardless of how many actually exist.

Debug metrics

Metric Name	Type	Description
`loki_rules_config_updates_total`	`counter`	Number of times the configuration has been updated.
`loki_rules_events_total`	`counter`	Number of events processed, partitioned by event type.
`loki_rules_events_failed_total`	`counter`	Number of events that failed to be processed, partitioned by event type.
`loki_rules_events_retried_total`	`counter`	Number of events that were retried, partitioned by event type.
`loki_rules_client_request_duration_seconds`	`histogram`	Duration of requests to the Loki API.

Example

This example creates a loki.rules.kubernetes component that loads discovered rules to a local Loki instance under the team-a tenant. Only namespaces and rules with the alloy label set to yes are included.

loki.rules.kubernetes "local" {
    address = "loki:3100"
    tenant_id = "team-a"

    rule_namespace_selector {
        match_labels = {
            alloy = "yes",
        }
    }

    rule_selector {
        match_labels = {
            alloy = "yes",
        }
    }
}

This example creates a loki.rules.kubernetes component that loads discovered rules to Grafana Cloud.

loki.rules.kubernetes "default" {
    address = "<GRAFANA_CLOUD_URL>"
    basic_auth {
        username = "<GRAFANA_CLOUD_USER>"
        password = "<GRAFANA_CLOUD_API_KEY>"
        // Alternatively, load the password from a file:
        // password_file = "<GRAFANA_CLOUD_API_KEY_PATH>"
    }
}

Replace the following:

<GRAFANA_CLOUD_URL>: The Grafana Cloud URL.
<GRAFANA_CLOUD_USER>: Your Grafana Cloud user name.
<GRAFANA_CLOUD_API_KEY>: Your Grafana Cloud API key.
<GRAFANA_CLOUD_API_KEY_PATH>: The path to the Grafana Cloud API key.

This example adds label matcher {cluster=~"prod-.*"} to all the queries discovered by loki.rules.kubernetes.

loki.rules.kubernetes "default" {
    address = "loki:3100"
    extra_query_matchers {
        matcher {
            name = "cluster"
            match_type = "=~"
            value = "prod-.*"
        }
    }
}

If a query in the form of {app="my-app"} is found in PrometheusRule CRDs, it will be modified to {app="my-app", cluster=~"prod-.*"} before sending it to Loki.

The following example is an RBAC configuration for Kubernetes. It authorizes Alloy to query the Kubernetes REST API:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: alloy
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: alloy
rules:
- apiGroups: [""]
  resources: ["namespaces"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["monitoring.coreos.com"]
  resources: ["prometheusrules"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: alloy
subjects:
- kind: ServiceAccount
  name: alloy
  namespace: default
roleRef:
  kind: ClusterRole
  name: alloy
  apiGroup: rbac.authorization.k8s.io

loki.secretfilter

Mon, 30 Mar 2026 15:47:22 +0000

`loki.secretfilter`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

loki.secretfilter receives log entries and redacts detected secrets from the log lines. The detection relies on regular expression patterns, defined in the Gitleaks configuration file embedded within the component. loki.secretfilter can also use a custom configuration file based on the Gitleaks configuration file structure.

Caution
Personally Identifiable Information (PII) isn’t currently in scope and some secrets could remain undetected. This component may generate false positives or redact too much. Don’t rely solely on this component to redact sensitive information.

Note
This component operates on log lines and doesn’t scan labels or other metadata.

Caution
Detecting secrets can be resource-intensive and can increase CPU usage significantly. Roll out this component gradually and monitor resource usage. Place loki.secretfilter after components that reduce log volume so it processes fewer lines.

Usage

loki.secretfilter "<LABEL>" {
    forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with loki.secretfilter:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`gitleaks_config`	`string`	Path to a custom Gitleaks TOML config file. If empty, the default Gitleaks config is used.	`""`	no
`origin_label`	`string`	Loki label to use for the `secrets_redacted_by_origin` metric. If empty, that metric is not registered.	`""`	no
`rate`	`float`	Entry sampling rate in `[0.0, 1.0]` where `1` processes all entries. Unsampled entries are forwarded unchanged.	`1.0`	no
`redact_with`	`string`	Template for the redaction placeholder. Use `$SECRET_NAME` and `$SECRET_HASH`, for example, `"<$SECRET_NAME:$SECRET_HASH>"`	`""`	no
`redact_percent`	`uint`	When `redact_with` is not set: percent of the secret to redact (1–100), where 100 is full redaction.	`80`	no
`drop_on_timeout`	`bool`	When true, drop entries that exceed `processing_timeout` instead of forwarding them unredacted.	`false`	no
`processing_timeout`	`duration`	Maximum time allowed to process a single log entry. `0` disables the timeout.	`0`	no

The gitleaks_config argument is the path to a custom Gitleaks TOML config file. The file supports the standard Gitleaks structure (rules, allowlists, and [extend] to extend the default config). If gitleaks_config is empty, the component uses the default Gitleaks configuration embedded in the component.

Note
The default configuration may change between Alloy versions. For consistent behavior, use an external configuration file via gitleaks_config.

Redaction behavior:

If redact_with is set, it is used as the replacement string for every detected secret. The supported placeholders are $SECRET_NAME (rule ID) and $SECRET_HASH (SHA1 hash of the secret).
If redact_with is not set, redaction is percentage-based (Gitleaks-style). redact_percent controls how much of the secret is redacted. For example, 80 shows the first 20% of the secret followed by "...". 100 replaces the entire secret with "REDACTED". When redact_percent is 0 or unset, 80% redaction is used.

Sampling: The rate argument controls what fraction of log entries are processed by the secret filter. Entries that Alloy does not select based on the sampling rate pass through unchanged, with no detection or redaction applied. Use a value below 1.0, for example, 0.1 for 10%, to reduce CPU usage when processing high-volume logs. Monitor loki_secretfilter_entries_bypassed_total to observe how many entries were skipped.

Origin metric: The origin_label argument specifies which Loki label to use for the secrets_redacted_by_origin metric, so you can track how many secrets were redacted per source or environment.

Processing timeout: The processing_timeout argument sets a maximum duration for processing each log entry. When the timeout is exceeded, the loki_secretfilter_lines_timed_out_total metric is incremented. By default (drop_on_timeout = false), the original unredacted entry is forwarded so no log lines are lost. When drop_on_timeout = true, entries that exceed the timeout are dropped and the loki_secretfilter_lines_dropped_total metric is incremented.

Caution
Setting drop_on_timeout = true means log lines can be silently dropped. A dropped line can’t be recovered, whereas an unredacted line containing a secret can still be detected and mitigated later. Use this option only when dropping lines is preferable to forwarding potentially unredacted data.

Blocks

The loki.secretfilter component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`receiver`	`LogsReceiver`	A value that other components can use to send log entries to.

Component health

loki.secretfilter is only reported as unhealthy if given an invalid configuration.

Debug metrics

loki.secretfilter exposes the following Prometheus metrics:

Name	Type	Description
`loki_secretfilter_entries_bypassed_total`	Counter	Total number of entries forwarded without processing due to sampling.
`loki_secretfilter_lines_dropped_total`	Counter	Total number of log lines dropped due to processing timeout, when `drop_on_timeout` is `true`.
`loki_secretfilter_lines_timed_out_total`	Counter	Total number of log lines that exceeded the processing timeout, whether dropped or forwarded.
`loki_secretfilter_processing_duration_seconds`	Summary	Time taken to process and redact logs, in seconds.
`loki_secretfilter_secrets_redacted_total`	Counter	Total number of secrets redacted.
`loki_secretfilter_secrets_redacted_by_rule_total`	Counter	Number of secrets redacted, partitioned by rule name.
`loki_secretfilter_secrets_redacted_by_origin`	Counter	Number of secrets redacted, partitioned by origin label, when `origin_label` is set.

Example

This example uses loki.secretfilter to redact secrets from log lines before forwarding them to a Loki receiver. It uses a custom redaction template with $SECRET_NAME and $SECRET_HASH.

Alternatively, you can:

Omit redact_with to use percentage-based redaction, which defaults to 80% redacted.
Set redact_percent to 100 for full redaction.
Set gitleaks_config to point to a custom Gitleaks TOML configuration file.
Set rate to a value below 1.0 to sample entries and reduce CPU usage; entries not selected are forwarded unchanged.

local.file_match "local_logs" {
    path_targets = "<PATH_TARGETS>"
}

loki.source.file "local_logs" {
    targets    = local.file_match.local_logs.targets
    forward_to = [loki.secretfilter.secret_filter.receiver]
}

loki.secretfilter "secret_filter" {
    forward_to  = [loki.write.local_loki.receiver]
    redact_with = "<ALLOY-REDACTED-SECRET:$SECRET_NAME:$SECRET_HASH>"
    // optional: gitleaks_config = "/etc/alloy/gitleaks.toml"
    // optional: redact_percent = 100  // use when redact_with is not set
}

loki.write "local_loki" {
    endpoint {
        url = "<LOKI_ENDPOINT>"
    }
}

Replace the following:

<PATH_TARGETS>: The paths to the log files to monitor.
<LOKI_ENDPOINT>: The URL of the Loki instance to send logs to.

Compatible components

loki.secretfilter can accept arguments from the following components:

Components that export Loki LogsReceiver

loki.secretfilter has exports that can be consumed by the following components:

Components that consume Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.api

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.api`

loki.source.api receives log entries over HTTP and forwards them to other loki.* components.

The HTTP API exposed is compatible with Loki push API and the logproto format. This means that other loki.write components can be used as a client and send requests to loki.source.api which enables using Alloy as a proxy for logs.

Usage

loki.source.api "<LABEL>" {
    http {
        listen_address = "<LISTEN_ADDRESS>"
        listen_port = "<PORT>"
    }
    forward_to = <RECEIVER_LIST>
}

The component starts an HTTP server on the configured port and address with the following endpoints:

/loki/api/v1/push - accepting POST requests compatible with Loki push API, for example, from another Alloy’s loki.write component.
/loki/api/v1/raw - accepting POST requests with newline-delimited log lines in body. This can be used to send NDJSON or plain text logs. This is compatible with the Promtail push API endpoint. Refer to the Promtail documentation for more information. When this endpoint is used, the incoming timestamps can’t be used and the use_incoming_timestamp = true setting is ignored.
/ready - accepting GET requests. Can be used to confirm the server is reachable and healthy.
/api/v1/push - internally reroutes to /loki/api/v1/push.
/api/v1/raw - internally reroutes to /loki/api/v1/raw.

Arguments

You can use the following arguments with loki.source.api:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`labels`	`map(string)`	The labels to associate with each received logs record.	`{}`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no
`use_incoming_timestamp`	`bool`	Whether to use the timestamp received from request.	`false`	no
`max_send_message_size`	`size`	Maximum size of a request to the push API.	`"100MiB"`	no
`graceful_shutdown_timeout`	`duration`	Timeout for server’s graceful shutdown. If configured, should be greater than zero.	`"30s"`	no

The relabel_rules field can make use of the rules export value from a loki.relabel component to apply one or more relabeling rules to log entries before they’re forwarded to the list of receivers in forward_to.

Blocks

You can use the following blocks with loki.source.api:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`http`

The http block configures the HTTP server.

You can use the following arguments to configure the http block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`conn_limit`	`int`	Maximum number of simultaneous HTTP connections. Defaults to no limit.	`0`	no
`listen_address`	`string`	Network address on which the server listens for new connections. Defaults to accepting all incoming connections.	`""`	no
`listen_port`	`int`	Port number on which the server listens for new connections.	`8080`	no
`server_idle_timeout`	`duration`	Idle timeout for HTTP server.	`"120s"`	no
`server_read_timeout`	`duration`	Read timeout for HTTP server.	`"30s"`	no
`server_write_timeout`	`duration`	Write timeout for HTTP server.	`"30s"`	no

`tls`

The tls block configures TLS for the HTTP server.

Name	Type	Description	Default	Required
`cert_pem`	`string`	PEM data of the server TLS certificate.	`""`	no
`cert_file`	`string`	Path to the server TLS certificate on disk.	`""`	no
`client_auth_type`	`string`	Client authentication to use.	`"NoClientCert"`	no
`client_ca_file`	`string`	Path to the client CA file on disk to validate requests against.	`""`	no
`client_ca_pem`	`string`	PEM data of the client CA to validate requests against.	`""`	no
`key_file`	`string`	Path to the server TLS key on disk.	`""`	no
`key_pem`	`secret`	PEM data of the server TLS key.	`""`	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

Exported fields

loki.source.api doesn’t export any fields.

Component health

loki.source.api is only reported as unhealthy if given an invalid configuration.

Debug metrics

The following are some of the metrics that are exposed when this component is used. The metrics include labels such as status_code where relevant, which can be used to measure request success rates.

loki_source_api_request_duration_seconds (histogram): HTTP request handling time, in seconds.
loki_source_api_inflight_requests (gauge): Current number of inflight requests.
loki_source_api_request_message_bytes (histogram): Request message size, in bytes.
loki_source_api_response_message_bytes (histogram): Response message size, in bytes.
loki_source_api_tcp_connections (gauge): Current number of accepted TCP connections.
loki_source_api_entries_written (counter): Total number of log entries forwarded.

Example

This example starts an HTTP server on 0.0.0.0 address and port 9999. The server receives log entries and forwards them to a loki.write component while adding a forwarded="true" label. The loki.write component sends the logs to the specified Loki instance using basic auth credentials provided.

loki.write "local" {
    endpoint {
        url = "http://loki:3100/api/v1/push"
        basic_auth {
            username = "<USERNAME>"
            password_file = "<PASSWORD_FILE>"
        }
    }
}

loki.source.api "loki_push_api" {
    http {
        listen_address = "0.0.0.0"
        listen_port = 9999
    }
    forward_to = [
        loki.write.local.receiver,
    ]
    labels = {
        forwarded = "true",
    }
}

Replace the following:

<USERNAME>: Your username.
<PASSWORD_FILE>: Your password file.

Technical details

loki.source.api filters out all labels that start with __, for example, __tenant_id__.

If you need to be able to set the tenant ID, you must either make sure the X-Scope-OrgID header is present or use the loki.process component.

Compatible components

loki.source.api can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.awsfirehose

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.awsfirehose`

loki.source.awsfirehose receives log entries over HTTP from Amazon Data Firehose and forwards them to other loki.* components.

The HTTP API exposed is compatible with the Data Firehose HTTP Delivery API. Since the API model that Data Firehose uses to deliver data over HTTP is generic enough, the same component can be used to receive data from multiple origins:

The component uses a heuristic to try to decode as much information as possible from each log record, and it falls back to writing the raw records to Loki. The decoding process goes as follows:

Data Firehose sends batched requests
Each record is treated individually
For each record received in each request:
- If the record comes from a CloudWatch logs subscription filter, it’s decoded and each logging event is written to Loki
- All other records are written raw to Loki

The component exposes some internal labels, available for relabeling. The following tables describes internal labels available in records coming from any source.

Name	Description	Example
`__aws_firehose_request_id`	Data Firehose request ID.	`a1af4300-6c09-4916-ba8f-12f336176246`
`__aws_firehose_source_arn`	Data Firehose delivery stream ARN.	`arn:aws:firehose:us-east-2:123:deliverystream/aws_firehose_test_stream`

If the source of the Data Firehose record is CloudWatch logs, the request is further decoded and enriched with even more labels, exposed as follows:

Name	Description	Example
`__aws_cw_log_group`	The log group name of the originating log data.	`CloudTrail/logs`
`__aws_cw_log_stream`	The log stream name of the originating log data.	`111111111111_CloudTrail/logs_us-east-1`
`__aws_cw_matched_filters`	The list of subscription filter names that match the originating log data. The list is encoded as a comma-separated list.	`Destination,Destination2`
`__aws_cw_msg_type`	Data messages use the `DATA_MESSAGE` type. Sometimes CloudWatch Logs may emit Amazon Kinesis Data Streams records with a `CONTROL_MESSAGE` type, mainly for checking if the destination is reachable.	`DATA_MESSAGE`
`__aws_owner`	The AWS Account ID of the originating log data.	`111111111111`

Refer to the Examples for a full example configuration showing how to enrich each log entry with these labels.

Usage

loki.source.awsfirehose "<LABEL>" {
    http {
        listen_address = "<LISTEN_ADDRESS>"
        listen_port = "<PORT>"
    }
    forward_to = RECEIVER_LIST
}

The component starts an HTTP server on the configured port and address with the following endpoints:

/awsfirehose/api/v1/push - accepting POST requests compatible with Data Firehose HTTP Specifications.

You can use the X-Amz-Firehose-Common-Attributes header to set extra static labels. You can configure the header in the Parameters section of the Data Firehose delivery stream configuration. Label names must be prefixed with lbl_. The prefix is removed before the label is stored in the log entry. Label names and label values must be compatible with the Prometheus data model specification.

Example of the valid X-Amz-Firehose-Common-Attributes value with two custom labels:

{
  "commonAttributes": {
    "lbl_label1": "value1",
    "lbl_label2": "value2"
  }
}

Arguments

You can use the following arguments with loki.source.awsfirehose:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`access_key`	`secret`	If set, require Data Firehose to provide a matching key.	`""`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no
`use_incoming_timestamp`	`bool`	Whether to use the timestamp received from the request.	`false`	no

Blocks

You can use the following blocks with loki.source.awsfirehose:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`http`

The http block configures the HTTP server.

You can use the following arguments to configure the http block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`conn_limit`	`int`	Maximum number of simultaneous HTTP connections. Defaults to no limit.	`0`	no
`listen_address`	`string`	Network address on which the server listens for new connections. Defaults to accepting all incoming connections.	`""`	no
`listen_port`	`int`	Port number on which the server listens for new connections.	`8080`	no
`server_idle_timeout`	`duration`	Idle timeout for HTTP server.	`"120s"`	no
`server_read_timeout`	`duration`	Read timeout for HTTP server.	`"30s"`	no
`server_write_timeout`	`duration`	Write timeout for HTTP server.	`"30s"`	no

`tls`

The tls block configures TLS for the HTTP and gRPC servers.

Name	Type	Description	Default	Required
`cert_pem`	`string`	PEM data of the server TLS certificate.	`""`	no
`cert_file`	`string`	Path to the server TLS certificate on disk.	`""`	no
`client_auth_type`	`string`	Client authentication to use.	`"NoClientCert"`	no
`client_ca_file`	`string`	Path to the client CA file on disk to validate requests against.	`""`	no
`client_ca_pem`	`string`	PEM data of the client CA to validate requests against.	`""`	no
`key_file`	`string`	Path to the server TLS key on disk.	`""`	no
`key_pem`	`secret`	PEM data of the server TLS key.	`""`	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

Exported fields

loki.source.awsfirehose doesn’t export any fields.

Component health

loki.source.awsfirehose is only reported as unhealthy if given an invalid configuration.

Debug metrics

The following are some of the metrics that are exposed when this component is used.

Note
The metrics include labels such as status_code where relevant, which you can use to measure request success rates.

loki_source_awsfirehose_batch_size (histogram): Size (in units) of the number of records received per request.
loki_source_awsfirehose_inflight_requests (gauge): Current number of inflight requests.
loki_source_awsfirehose_request_duration_seconds (histogram): HTTP request handling time, in seconds.
loki_source_awsfirehose_invalid_static_labels_errors (counter): Count number of errors while processing Data Firehose static labels.
loki_source_awsfirehose_request_message_bytes (histogram): Request message size, in bytes.
loki_source_awsfirehose_response_message_bytes (histogram): Response message size, in bytes.
loki_source_awsfirehose_record_errors (counter): Count of errors while decoding an individual record.
loki_source_awsfirehose_records_received (counter): Count of records received.
loki_source_awsfirehose_request_errors (counter): Count of errors while receiving a request.
loki_source_awsfirehose_tcp_connections (gauge): Current number of accepted TCP connections.

Example

This example starts an HTTP server on 0.0.0.0 address and port 9999. The server receives log entries and forwards them to a loki.write component. The loki.write component sends the logs to the specified Loki instance using basic auth credentials provided.

loki.write "local" {
    endpoint {
        url = "http://loki:3100/api/v1/push"
        basic_auth {
            username = "<USERNAME>"
            password_file = "<PASSWORD_FILE>"
        }
    }
}

loki.source.awsfirehose "loki_fh_receiver" {
    http {
        listen_address = "0.0.0.0"
        listen_port = 9999
    }
    forward_to = [
        loki.write.local.receiver,
    ]
}

Replace the following:

<USERNAME>: Your username.
<PASSWORD_FILE>: Your password file.

As another example, if you are receiving records that originated from a CloudWatch logs subscription, you can enrich each received entry by relabeling internal labels. The following configuration builds upon the one above but keeps the origin log stream and group as log_stream and log_group, respectively.

loki.write "local" {
    endpoint {
        url = "http://loki:3100/api/v1/push"
        basic_auth {
            username = "<USERNAME>"
            password_file = "<PASSWORD_FILE>"
        }
    }
}

loki.source.awsfirehose "loki_fh_receiver" {
    http {
        listen_address = "0.0.0.0"
        listen_port = 9999
    }
    forward_to = [
        loki.write.local.receiver,
    ]
    relabel_rules = loki.relabel.logging_origin.rules
}

loki.relabel "logging_origin" {
  rule {
    action = "replace"
    source_labels = ["__aws_cw_log_group"]
    target_label = "log_group"
  }
  rule {
    action = "replace"
    source_labels = ["__aws_cw_log_stream"]
    target_label = "log_stream"
  }
  forward_to = []
}

Replace the following:

<USERNAME>: Your username.
<PASSWORD_FILE>: Your password file.

Compatible components

loki.source.awsfirehose can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.azure_event_hubs

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.azure_event_hubs`

loki.source.azure_event_hubs receives Azure Event Hubs messages by making use of an Apache Kafka endpoint on Event Hubs. Refer to the Azure Event Hubs documentation for more information.

To learn more about streaming Azure logs to an Azure Event Hubs, refer to Microsoft’s tutorial on how to Stream Azure Active Directory logs to an Azure event hub.

An Apache Kafka endpoint isn’t available within the Basic pricing plan. Refer to the Event Hubs pricing page for more information.

You can specify multiple loki.source.azure_event_hubs components by giving them different labels.

Usage

loki.source.azure_event_hubs "<LABEL>" {
    fully_qualified_namespace = "<HOST:PORT>"
    event_hubs                = "<EVENT_HUB_LIST>"
    forward_to                = <RECEIVER_LIST>

    authentication {
        mechanism = "AUTHENTICATION_MECHANISM"
    }
}

Arguments

You can use the following arguments with loki.source.azure_event_hubs:

Name	Type	Description	Default	Required
`event_hubs`	`list(string)`	Event Hubs to consume.		yes
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`fully_qualified_namespace`	`string`	Event hub namespace.		yes
`assignor`	`string`	The consumer group rebalancing strategy to use.	`"range"`	no
`disallow_custom_messages`	`bool`	Whether to ignore messages that don’t match the schema for Azure resource logs.	`false`	no
`group_id`	`string`	The Kafka consumer group ID.	`"loki.source.azure_event_hubs"`	no
`labels`	`map(string)`	The labels to associate with each received event.	`{}`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no
`use_incoming_timestamp`	`bool`	Whether to use the timestamp received from Azure Event Hub.	`false`	no

The fully_qualified_namespace argument must refer to a full HOST:PORT that points to your event hub, such as NAMESPACE.servicebus.windows.net:9093. The assignor argument must be set to one of "range", "roundrobin", or "sticky".

Labels

The labels map is applied to every message that the component reads.

The following internal labels prefixed with __ are available but are discarded if not relabeled:

__azure_event_hubs_category
__meta_kafka_group_id
__meta_kafka_member_id
__meta_kafka_message_key
__meta_kafka_partition
__meta_kafka_topic

Blocks

You can use the following block with loki.source.azure_event_hubs:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`authentication`

Required

The authentication block defines the authentication method when communicating with Azure Event Hub.

Name	Type	Description	Required
`mechanism`	`string`	Authentication mechanism.	yes
`connection_string`	`secret`	Event Hubs ConnectionString for authentication on Azure Cloud.	no
`scopes`	`list(string)`	Access token scopes. Default is `fully_qualified_namespace` without port.	no

mechanism supports the values "connection_string" and "oauth". If "connection_string" is used, you must set the connection_string attribute. If "oauth" is used, you must configure one of the supported credential types via environment variables or Azure CLI.

Exported fields

loki.source.azure_event_hubs doesn’t export any fields.

Component health

loki.source.azure_event_hubs is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.azure_event_hubs doesn’t expose additional debug info.

Example

This example consumes messages from Azure Event Hub and uses OAuth 2.0 to authenticate itself.

loki.source.azure_event_hubs "example" {
    fully_qualified_namespace = "my-ns.servicebus.windows.net:9093"
    event_hubs                = ["gw-logs"]
    forward_to                = [loki.write.example.receiver]

    authentication {
        mechanism = "oauth"
    }
}

loki.write "example" {
    endpoint {
        url = "loki:3100/api/v1/push"
    }
}

Compatible components

loki.source.azure_event_hubs can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.cloudflare

Mon, 30 Mar 2026 15:47:22 +0000

`loki.source.cloudflare`

loki.source.cloudflare pulls logs from the Cloudflare Logpull API and forwards them to other loki.* components.

These logs contain data related to the connecting client, the request path through the Cloudflare network, and the response from the origin web server and can be useful for enriching existing logs on an origin server.

You can specify multiple loki.source.cloudflare components by giving them different labels.

Usage

loki.source.cloudflare "<LABEL>" {
  zone_id   = "<ZONE_ID>"
  api_token = "<API_TOKEN>"

  forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with loki.source.cloudflare:

Name	Type	Description	Default	Required
`api_token`	`secret`	The API token to authenticate with.		yes
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`zone_id`	`string`	The Cloudflare zone ID to use.		yes
`additional_fields`	`list(string)`	The additional list of fields to supplement those provided via `fields_type`.		no
`fields_type`	`string`	The set of fields to fetch for log entries.	`"default"`	no
`labels`	`map(string)`	The labels to associate with incoming log entries.	`{}`	no
`pull_range`	`duration`	The timeframe to fetch for each pull request.	`"1m"`	no
`workers`	`int`	The number of workers to use for parsing logs.	`3`	no

By default loki.source.cloudflare fetches logs with the default set of fields. The following list shows the different sets of fields_type available for selection, and the fields they include:

default includes:
- "ClientIP"
- "ClientRequestHost"
- "ClientRequestMethod"
- "ClientRequestURI"
- "EdgeEndTimestamp"
- "EdgeResponseBytes"
- "EdgeRequestHost"
- "EdgeResponseStatus"
- "EdgeStartTimestamp"
- "RayID"
plus any extra fields provided via additional_fields argument.
minimal includes all default fields and adds:
- "ZoneID"
- "ClientSSLProtocol"
- "ClientRequestProtocol"
- "ClientRequestPath"
- "ClientRequestUserAgent"
- "ClientRequestReferer"
- "EdgeColoCode"
- "ClientCountry"
- "CacheCacheStatus"
- "CacheResponseStatus"
- "EdgeResponseContentType"
plus any extra fields provided via additional_fields argument.
extended includes all minimal fields and adds:
- "ClientSSLCipher"
- "ClientASN"
- "ClientIPClass"
- "CacheResponseBytes"
- "EdgePathingOp"
- "EdgePathingSrc"
- "EdgePathingStatus"
- "ParentRayID"
- "WorkerCPUTime"
- "WorkerStatus"
- "WorkerSubrequest"
- "WorkerSubrequestCount"
- "OriginIP"
- "OriginResponseStatus"
- "OriginSSLProtocol"
- "OriginResponseHTTPExpires"
- "OriginResponseHTTPLastModified"
plus any extra fields provided via additional_fields argument.
all includes all extended fields and adds:
- "BotScore"
- "BotScoreSrc"
- "BotTags"
- "ClientRequestBytes"
- "ClientSrcPort"
- "ClientXRequestedWith"
- "CacheTieredFill"
- "EdgeResponseCompressionRatio"
- "EdgeServerIP"
- "FirewallMatchesSources"
- "FirewallMatchesActions"
- "FirewallMatchesRuleIDs"
- "OriginResponseBytes"
- "OriginResponseTime"
- "ClientDeviceType"
- "WAFFlags"
- "WAFMatchedVar"
- "EdgeColoID"
- "RequestHeaders"
- "ResponseHeaders"
- "ClientRequestSource"
plus any extra fields provided via additional_fields argument. This is still relevant in this case if new fields are made available via Cloudflare API but aren’t yet included in all.
custom includes only the fields defined in additional_fields.

The component saves the last successfully fetched timestamp in its positions file. If a position is found in the file for a given zone ID, the component restarts pulling logs from that timestamp. When no position is found, the component starts pulling logs from the current time.

Logs are fetched using multiple workers which request the last available pull_range repeatedly. It’s possible to fall behind due to having too many log lines to process for each pull. Adding more workers, decreasing the pull range, or decreasing the quantity of fields fetched can mitigate this performance issue.

The last timestamp fetched by the component is recorded in the loki_source_cloudflare_target_last_requested_end_timestamp debug metric.

All incoming Cloudflare log entries are in JSON format. You can use the loki.process component and a JSON processing stage to extract more labels or change the log line format. A sample log looks like this:

{
    "CacheCacheStatus": "miss",
    "CacheResponseBytes": 8377,
    "CacheResponseStatus": 200,
    "CacheTieredFill": false,
    "ClientASN": 786,
    "ClientCountry": "gb",
    "ClientDeviceType": "desktop",
    "ClientIP": "100.100.5.5",
    "ClientIPClass": "noRecord",
    "ClientRequestBytes": 2691,
    "ClientRequestHost": "www.foo.com",
    "ClientRequestMethod": "GET",
    "ClientRequestPath": "/comments/foo/",
    "ClientRequestProtocol": "HTTP/1.0",
    "ClientRequestReferer": "https://www.foo.com/foo/168855/?offset=8625",
    "ClientRequestURI": "/foo/15248108/",
    "ClientRequestUserAgent": "some bot",
    "ClientRequestSource": "1"
    "ClientSSLCipher": "ECDHE-ECDSA-AES128-GCM-SHA256",
    "ClientSSLProtocol": "TLSv1.2",
    "ClientSrcPort": 39816,
    "ClientXRequestedWith": "",
    "EdgeColoCode": "MAN",
    "EdgeColoID": 341,
    "EdgeEndTimestamp": 1637336610671000000,
    "EdgePathingOp": "wl",
    "EdgePathingSrc": "macro",
    "EdgePathingStatus": "nr",
    "EdgeRateLimitAction": "",
    "EdgeRateLimitID": 0,
    "EdgeRequestHost": "www.foo.com",
    "EdgeResponseBytes": 14878,
    "EdgeResponseCompressionRatio": 1,
    "EdgeResponseContentType": "text/html",
    "EdgeResponseStatus": 200,
    "EdgeServerIP": "8.8.8.8",
    "EdgeStartTimestamp": 1637336610517000000,
    "FirewallMatchesActions": [],
    "FirewallMatchesRuleIDs": [],
    "FirewallMatchesSources": [],
    "OriginIP": "8.8.8.8",
    "OriginResponseBytes": 0,
    "OriginResponseHTTPExpires": "",
    "OriginResponseHTTPLastModified": "",
    "OriginResponseStatus": 200,
    "OriginResponseTime": 123000000,
    "OriginSSLProtocol": "TLSv1.2",
    "ParentRayID": "00",
    "RayID": "6b0a...",
    "RequestHeaders": [],
    "ResponseHeaders": [
      "x-foo": "bar"
    ],
    "SecurityLevel": "med",
    "WAFAction": "unknown",
    "WAFFlags": "0",
    "WAFMatchedVar": "",
    "WAFProfile": "unknown",
    "WAFRuleID": "",
    "WAFRuleMessage": "",
    "WorkerCPUTime": 0,
    "WorkerStatus": "unknown",
    "WorkerSubrequest": false,
    "WorkerSubrequestCount": 0,
    "ZoneID": 1234
}

Blocks

The loki.source.cloudflare component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

loki.source.cloudflare doesn’t export any fields.

Component health

loki.source.cloudflare is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.cloudflare exposes the following debug information:

Whether the target is ready and reading logs from the API.
The Cloudflare zone ID.
The last error reported, if any.
The stored positions file entry, as the combination of zone_id, labels and last fetched timestamp.
The last timestamp fetched.
The set of fields being fetched.

Debug metrics

loki_source_cloudflare_target_entries_total (counter): Total number of successful entries sent via the cloudflare target.
loki_source_cloudflare_target_last_requested_end_timestamp (gauge): The last cloudflare request end timestamp fetched, for calculating how far behind the target is.

Example

This example pulls logs from Cloudflare’s API and forwards them to a loki.write component.

loki.source.cloudflare "dev" {
  zone_id   = sys.env("CF_ZONE_ID")
  api_token = local.file.api.content

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.cloudflare can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.docker

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.docker`

loki.source.docker reads log entries from Docker containers and forwards them to other loki.* components. Each component can read from a single Docker daemon.

You can specify multiple loki.source.docker components by giving them different labels.

Usage

loki.source.docker "LABEL" {
  host       = HOST
  targets    = TARGET_LIST
  forward_to = RECEIVER_LIST
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.docker:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`host`	`string`	Address of the Docker daemon.		yes
`labels`	`map(string)`	The default set of labels to apply on entries.	`{}`	yes
`targets`	`list(map(string))`	List of containers to read logs from.		yes
`refresh_interval`	`duration`	The refresh interval to use when connecting to the Docker daemon over HTTP(S).	`"60s"`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no

Blocks

You can use the following blocks with loki.source.docker:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

These blocks are only applicable when connecting to a Docker daemon over HTTP or HTTPS and has no effect when connecting via a unix:/// socket

`http_client_config`

The http_client_config block configures settings used to connect to HTTP(S) Docker daemons.

Name	Type	Description	Default	Required
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no

bearer_token, bearer_token_file, basic_auth, authorization, and oauth2 are mutually exclusive, and only one can be provided inside of a http_client_config block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

The authorization block configures custom authorization to use for the Docker daemon.

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

The basic_auth block configures basic authentication for HTTP(S) Docker daemons.

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`oauth2`

The oauth2 block configures OAuth 2.0 authorization to use for the Docker daemon.

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

The tls_config block configures TLS settings for connecting to HTTPS Docker daemons.

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

loki.source.docker doesn’t export any fields.

Component health

loki.source.docker is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.docker exposes some debug information per target:

Whether the target is ready to tail entries.
The labels associated with the target.
The most recent time a log line was read.

Debug metrics

loki_source_docker_target_entries_total (gauge): Total number of successful entries sent to the Docker target.
loki_source_docker_target_parsing_errors_total (gauge): Total number of parsing errors while receiving Docker messages.

Component behavior

The component uses its data path, a directory named after the domain’s fully qualified name, to store its positions file. The positions file is used to store read offsets, so that if a component or Alloy restarts, loki.source.docker can pick up tailing from the same spot.

If the target’s argument contains multiple entries with the same container ID, for example, as a result of discovery.docker picking up multiple exposed ports or networks, loki.source.docker deduplicates them, and only keeps the first of each container ID instances, based on the __meta_docker_container_id label. As such, the Docker daemon is queried for each container ID only once, and only one target is available in the component’s debug info.

Example

This example collects log entries from the files specified in the targets argument and forwards them to a loki.write component to be written to Loki.

discovery.docker "linux" {
  host = "unix:///var/run/docker.sock"
}

loki.source.docker "default" {
  host       = "unix:///var/run/docker.sock"
  targets    = discovery.docker.linux.targets
  labels     = {"app" = "docker"}
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "http://loki:3100/loki/api/v1/push"
  }
}

Compatible components

loki.source.docker can accept arguments from the following components:

Components that export Targets
Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.file

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.file`

loki.source.file reads log entries from files and forwards them to other loki.* components. New log entries are forwarded whenever a log entry line ends with the \n character.

You can specify multiple loki.source.file components by giving them different labels.

Note
By default, loki.source.file requires absolute file paths in the targets argument. To discover files using glob patterns, you can either enable the file_match block (recommended) for built-in file discovery, or use the local.file_match component for file discovery and pass its targets to loki.source.file.

Refer to the File globbing example for more information.

Usage

loki.source.file "<LABEL>" {
  targets    = <TARGET_LIST>
  forward_to = <RECEIVER_LIST>
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.file:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`targets`	`list(map(string))`	List of files to read from.		yes
`encoding`	`string`	The encoding to convert from when reading files.	`""`	no
`legacy_positions_file`	`string`	Allows conversion from legacy positions file.	`""`	no
`on_positions_file_error`	`string`	How to handle a corrupt positions file entry for a given file.	`"restart_from_beginning"`	no
`tail_from_end`	`bool`	Whether to tail from end if a stored position isn’t found.	`false`	no

The encoding argument must be a valid IANA encoding name and if not set, it defaults to UTF-8. Alloy can automatically change the encoding to UTF-16 if the file includes a Byte Order Mark (BOM) for either UTF-16BE or UTF-16LE. The BOM will be taken into account even if Alloy resumes tailing a file from the middle of the file. This can happen after Alloy is restarted.

You can use the tail_from_end argument when you want to tail a large file without reading its entire content. When set to true, only new logs are read, ignoring the existing ones.

The on_positions_file_error argument must be one of "skip", "restart_from_end", or "restart_from_beginning". This attribute defines the behavior if the positions file entry for a given file is corrupted. "restart_from_end" will mimic the tail_from_end flag and set the position to the end of the file. This will reduce the likelihood of duplicate logs, but may cause some logs to not be sent. "restart_from_beginning" will reset the position to 0, causing the whole file to be read and processed. This may cause duplicate logs to be sent. "skip" will cause the tailer to skip the file and not collect its logs.

tail_from_end and a on_positions_file_error value of "restart_from_end" are not supported when decompression is enabled.

The legacy_positions_file argument is used when you are transitioning from Grafana Agent Static Mode to Grafana Alloy. The format of the positions file is different in Grafana Alloy, so this will convert it to the new format. This operation only occurs if the new positions file doesn’t exist and the legacy_positions_file is valid. When legacy_positions_file is set, Alloy will try to find previous positions for a given file by matching the path and labels, falling back to matching on path only if no match is found.

Blocks

You can use the following blocks with loki.source.file:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`decompression`

The decompression block contains configuration for reading logs from compressed files. The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	Whether decompression is enabled.		yes
`format`	`string`	Compression format.		yes
`initial_delay`	`duration`	Time to wait before starting to read from new compressed files.	0	no

If you compress a file under a folder being scraped, loki.source.file might try to ingest your file before you finish compressing it. To avoid it, pick an initial_delay that’s long enough to avoid it.

Currently supported compression formats are:

gz - for Gzip
z - for zlib
bz2 - for bzip2

The component can only support one compression format at a time. To handle multiple formats, you must create multiple components.

`file_watch`

The file_watch block configures how often log files are polled from disk for changes. The following arguments are supported:

Name	Type	Description	Default	Required
`max_poll_frequency`	`duration`	Maximum frequency to poll for files.	250ms	no
`min_poll_frequency`	`duration`	Minimum frequency to poll for files.	250ms	no

If no file changes are detected, the poll frequency doubles until a file change is detected or the poll frequency reaches the max_poll_frequency.

If file changes are detected, the poll frequency is reset to min_poll_frequency.

`file_match`

The file_match block enables built-in file discovery directly within loki.source.file. When enabled, the component discovers files on the local filesystem using glob patterns and the doublestar library.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	Enable file discovery using glob patterns.	`false`	no
`ignore_older_than`	`duration`	Ignores files with modification times before this duration.	`"0s"`	no
`sync_period`	`duration`	How often to sync filesystem and targets.	`"10s"`	no

Benefits of using file_match over local.file_match:

Simplified configuration: No need for a separate local.file_match component
Reduced overhead: File discovery is integrated directly into loki.source.file, eliminating the need for component-to-component communication
Same functionality: Supports the same glob patterns and features, including __path_exclude__ for excluding files

When enabled is set to true, you can use glob patterns, for example, /tmp/*.log or /var/log/**/*.log, directly in the targets argument’s __path__ label. The component periodically scans the filesystem based on sync_period and automatically discovers new files, removes deleted files, and ignores files older than ignore_older_than if specified.

The glob patterns support the {a,b,c} syntax for matching multiple alternatives:

/tmp/*.{log,txt,json} matches files with .log, .txt, or .json extensions.
/var/log/{nginx,apache}/*.log matches .log files in either the nginx or apache subdirectories.

Exported fields

loki.source.file doesn’t export any fields.

Component health

loki.source.file is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.file exposes some target-level debug information per reader:

The tailed path.
Whether the reader is running.
The last recorded read offset in the positions file.

Debug metrics

loki_source_file_file_bytes_total (gauge): Number of bytes total.
loki_source_file_files_active_total (gauge): Number of active files.
loki_source_file_read_bytes_total (gauge): Number of bytes read.
loki_source_file_read_lines_total (counter): Number of lines read.

Component behavior

If the decompression feature is deactivated, the component continuously monitors and tails the files. The component remains active after reaching the end of a file, and reads new entries in real-time as they’re appended to the file.

Each element in the list of targets as a set of key-value pairs called labels. The set of targets can either be static, or dynamically provided periodically by a service discovery component. The special label __path__ must always be present and must contain the absolute path of the file to read from.

The __path__ value is available as the filename label to each log entry the component reads. All other labels starting with a double underscore are considered internal and are removed from the log entries before they’re passed to other loki.* components.

The component uses its data path, a directory named after the domain’s fully qualified name, to store its positions file. The positions file stores read offsets, so that if a component or Alloy restarts, loki.source.file can pick up tailing from the same spot.

The data path is inside the directory configured by the --storage.path command line argument.

If a file is removed from the targets list, its positions file entry is also removed. When it’s added back on, loki.source.file starts reading it from the beginning.

Examples

The following examples demonstrate how you can collect log entries with loki.source.file.

Static targets

This example collects log entries from the files specified in the targets argument and forwards them to a loki.write component.

loki.source.file "tmpfiles" {
  targets    = [
    {__path__ = "/tmp/foo.txt", "color" = "pink"},
    {__path__ = "/tmp/bar.txt", "color" = "blue"},
    {__path__ = "/tmp/baz.txt", "color" = "grey"},
  ]
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

File globbing with `file_match` (recommended)

This example collects log entries from files matching the *.log pattern using the built-in file_match block. When files appear or disappear, the list of targets is automatically updated based on the sync_period configuration.

loki.source.file "tmpfiles" {
  targets    = [
    {__path__ = "/tmp/*.log"},
  ]
  forward_to = [loki.write.local.receiver]
  file_match {
    enabled = true
    sync_period = "10s"
  }
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

File globbing with `local.file_match`

This example demonstrates the alternative approach using a separate local.file_match component. This approach is still supported but using the file_match block is recommended for better performance and simpler configuration.

local.file_match "logs" {
  path_targets = [
    {__path__ = "/tmp/*.log"},
  ]
}

loki.source.file "tmpfiles" {
  targets    = local.file_match.logs.targets
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Match multiple patterns

This example shows how to use the {a,b,c} pattern syntax to match multiple file extensions, multiple directories, and exclude multiple file types in a single configuration.

loki.source.file "logs" {
  targets    = [
    // Match .log, .txt, and .json files from nginx, apache, or caddy directories
    // Exclude compressed and backup files
    {
      __path__         = "/var/log/{nginx,apache,caddy}/*.{log,txt,json}",
      __path_exclude__ = "/var/log/{nginx,apache,caddy}/*.{gz,zip,bak,old}",
      "job"            = "webserver",
    },
  ]
  forward_to = [loki.write.local.receiver]
  file_match {
    enabled = true
  }
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Decompression

This example collects log entries from compressed files matching the *.gz pattern using the built-in file_match block with decompression enabled.

loki.source.file "tmpfiles" {
  targets    = [
    {__path__ = "/tmp/*.gz"},
  ]
  forward_to = [loki.write.local.receiver]
  file_match {
    enabled = true
    sync_period = "10s"
  }
  decompression {
    enabled       = true
    initial_delay = "10s"
    format        = "gz"
  }
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.file can accept arguments from the following components:

Components that export Targets
Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.gcplog

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.gcplog`

loki.source.gcplog retrieves logs from cloud resources such as GCS buckets, load balancers, or Kubernetes clusters running on GCP by making use of Pub/Sub subscriptions.

The component uses either the ‘push’ or ‘pull’ strategy to retrieve log entries and forward them to the list of receivers in forward_to.

You can specify multiple loki.source.gcplog components by giving them different labels.

Usage

loki.source.gcplog "<LABEL>" {
  pull {
    project_id   = "<PROJECT_ID>"
    subscription = "<SUB_ID>"
  }

  forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with loki.source.gcplog:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no

Blocks

You can use the following blocks with loki.source.gcplog:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

The pull and push inner blocks are mutually exclusive. A component must contain exactly one of the two in its definition. The http and grpc block are just used when the push block is configured.

`pull`

The pull block defines which GCP project ID and subscription to read log entries from.

The following arguments can be used to configure the pull block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`project_id`	`string`	The GCP project id the subscription belongs to.		yes
`subscription`	`string`	The subscription to pull logs from.		yes
`labels`	`map(string)`	Additional labels to associate with incoming logs.	`{}`	no
`use_full_line`	`bool`	Send the full line from Cloud Logging even if `textPayload` is available.	`false`	no
`use_incoming_timestamp`	`bool`	Whether to use the incoming log timestamp.	`false`	no

The following blocks can be used to configure the pull block:

Name	Description	Required
[`limit`][limit]	Configures Pub/Sub flow-control limits for in-flight message processing.	no

To make use of the pull strategy, the GCP project must have been configured to forward its cloud resource logs onto a Pub/Sub topic for loki.source.gcplog to consume.

Typically, the host system also needs to have its GCP credentials configured. One way to do it, is to point the GOOGLE_APPLICATION_CREDENTIALS environment variable to the location of a credential configuration JSON file or a service account key.

`limit`

The limit block configures flow-control budgets for unprocessed Pub/Sub messages. When either budget is reached, Pub/Sub delivery is throttled, which limits concurrent in-flight message handling.

Name	Type	Description	Default	Required
`max_outstanding_bytes`	`string`	Byte budget for unprocessed messages, hitting this budget throttles delivery concurrency.	`"1GiB"`	no
`max_outstanding_messages`	`int`	Count budget for unprocessed messages, hitting this budget caps in-flight concurrency.	`1000`	no

`push`

The push block defines the configuration of the server that receives push requests from the GCP Pub/Sub servers.

The following arguments can be used to configure the push block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`graceful_shutdown_timeout`	`duration`	Timeout for servers graceful shutdown. If configured, should be greater than zero.	`"30s"`	no
`labels`	`map(string)`	Additional labels to associate with incoming entries.	`{}`	no
`push_timeout`	`duration`	Sets a maximum processing time for each incoming GCP log entry.	`"0s"`	no
`use_full_line`	`bool`	Send the full line from Cloud Logging even if `textPayload` is available. If `textPayload` is present in the line, it’s used as log line.	`false`	no
`use_incoming_timestamp`	`bool`	Whether to use the incoming entry timestamp.	`false`	no

The server listens for POST requests from GCP Push subscriptions on HOST:PORT/gcp/api/v1/push.

By default, for both strategies the component assigns the log entry timestamp as the time it was processed, except if use_incoming_timestamp is set to true.

The labels map is applied to every entry that passes through the component.

`grpc`

The grpc block configures the gRPC server.

You can use the following arguments to configure the grpc block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`conn_limit`	`int`	Maximum number of simultaneous HTTP connections. Defaults to no limit.	`0`	no
`listen_address`	`string`	Network address on which the server listens for new connections. It defaults to accepting all incoming connections.	`""`	no
`listen_port`	`int`	Port number on which the server listens for new connections. Defaults to a random free port.	`0`	no
`max_connection_age_grace`	`duration`	An additive period after `max_connection_age` after which the connection is forcibly closed.	`"infinity"`	no
`max_connection_age`	`duration`	The duration for the maximum time a connection may exist before it’s closed.	`"infinity"`	no
`max_connection_idle`	`duration`	The duration after which an idle connection is closed.	`"infinity"`	no
`server_max_concurrent_streams`	`int`	Limit on the number of concurrent streams for gRPC calls (0 = unlimited).	`100`	no
`server_max_recv_msg_size`	`int`	Limit on the size of a gRPC message this server can receive (bytes).	`4MB`	no
`server_max_send_msg_size`	`int`	Limit on the size of a gRPC message this server can send (bytes).	`4MB`	no

`http`

The http block configures the HTTP server.

You can use the following arguments to configure the http block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`conn_limit`	`int`	Maximum number of simultaneous HTTP connections. Defaults to no limit.	`0`	no
`listen_address`	`string`	Network address on which the server listens for new connections. Defaults to accepting all incoming connections.	`""`	no
`listen_port`	`int`	Port number on which the server listens for new connections.	`8080`	no
`server_idle_timeout`	`duration`	Idle timeout for HTTP server.	`"120s"`	no
`server_read_timeout`	`duration`	Read timeout for HTTP server.	`"30s"`	no
`server_write_timeout`	`duration`	Write timeout for HTTP server.	`"30s"`	no

`tls`

The tls block configures TLS for the HTTP and gRPC servers.

Name	Type	Description	Default	Required
`cert_pem`	`string`	PEM data of the server TLS certificate.	`""`	no
`cert_file`	`string`	Path to the server TLS certificate on disk.	`""`	no
`client_auth_type`	`string`	Client authentication to use.	`"NoClientCert"`	no
`client_ca_file`	`string`	Path to the client CA file on disk to validate requests against.	`""`	no
`client_ca_pem`	`string`	PEM data of the client CA to validate requests against.	`""`	no
`key_file`	`string`	Path to the server TLS key on disk.	`""`	no
`key_pem`	`secret`	PEM data of the server TLS key.	`""`	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

Exported fields

loki.source.gcplog doesn’t export any fields.

Component health

loki.source.gcplog is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.gcplog exposes some debug information per gcplog listener:

The configured strategy.
Their label set.
When using a push strategy, the listen address.

Debug metrics

When using the pull strategy, the component exposes the following debug metrics:

loki_source_gcplog_pull_entries_total (counter): Number of entries received by the gcplog target.
loki_source_gcplog_pull_last_success_scrape (gauge): Timestamp of target’s last successful poll.
loki_source_gcplog_pull_parsing_errors_total (counter): Total number of parsing errors while receiving gcplog messages.

When using the push strategy, the component exposes the following debug metrics:

loki_source_gcplog_push_inflight_requests (gauge): Current number of inflight requests.
loki_source_gcplog_push_request_duration_seconds (histogram): HTTP request handling time, in seconds.
loki_source_gcplog_push_request_message_bytes (histogram): Request message size, in bytes.
loki_source_gcplog_push_response_message_bytes (histogram): Response message size, in bytes.
loki_source_gcplog_push_tcp_connections (gauge): Current number of accepted TCP connections.
loki_source_gcplog_push_entries_total (counter): Number of entries received by the gcplog target.
loki_source_gcplog_push_parsing_errors_total (counter): Number of parsing errors while receiving gcplog messages.

Example

This example listens for GCP Pub/Sub PushRequests on 0.0.0.0:8080 and forwards them to a loki.write component.

loki.source.gcplog "local" {
  push {}

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

This example listens for GCP Pub/Sub PushRequests on 0.0.0.0:4040, and forwards them to a loki.write component.

loki.source.gcplog "local" {
  push {
    http {
        listen_port = 4040
    }
  }

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.gcplog can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.gelf

Mon, 30 Mar 2026 15:47:22 +0000

`loki.source.gelf`

loki.source.gelf reads Graylog Extended Long Format (GELF) logs from a UDP listener and forwards them to other loki.* components.

You can specify multiple loki.source.gelf components by giving them different labels and ports.

Usage

loki.source.gelf "<LABEL>" {
  forward_to    = <RECEIVER_LIST>
}

Arguments

The component starts a new UDP listener and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.gelf:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`listen_address`	`string`	UDP address and port to listen for Graylog messages.	`"0.0.0.0:12201"`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no
`use_incoming_timestamp`	`bool`	When false, assigns the current timestamp to the log when it was processed	`false`	no

Note
GELF logs can be sent uncompressed or compressed with GZIP or ZLIB. A job label is added with the full name of the component loki.source.gelf.LABEL.

The relabel_rules argument can make use of the rules export from a loki.relabel component to apply one or more relabeling rules to log entries before they’re forwarded to the list of receivers specified in forward_to.

Incoming messages have the following internal labels available:

__gelf_message_facility: The GELF facility.
__gelf_message_version: The GELF message version sent by the client.
__gelf_message_host: The host sending the GELF message.
__gelf_message_level: The GELF level as a string.

All labels starting with __ are removed prior to forwarding log entries. To keep these labels, relabel them using a loki.relabel component and pass its rules export to the relabel_rules argument.

Blocks

The loki.source.gelf component doesn’t support any blocks. You can configure this component with arguments.

Component health

loki.source.gelf is only reported as unhealthy if given an invalid configuration.

Debug Metrics

gelf_target_entries_total (counter): Total number of successful entries sent to the GELF target.
gelf_target_parsing_errors_total (counter): Total number of parsing errors while receiving GELF messages.

Example

loki.relabel "gelf" {
  rule {
    source_labels = ["__gelf_message_host"]
    target_label  = "host"
  }
}

loki.source.gelf "listen"  {
  forward_to    = [loki.write.endpoint.receiver]
  relabel_rules = loki.relabel.gelf.rules
}

loki.write "endpoint" {
  endpoint {
    url ="loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.gelf can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.heroku

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.heroku`

loki.source.heroku listens for Heroku messages over TCP connections and forwards them to other loki.* components.

The component starts a new Heroku listener for the given listener block and fans out incoming entries to the list of receivers in forward_to.

Before using loki.source.heroku, Heroku should be configured with the URL where Alloy is listening. Follow the steps in Heroku HTTPS Drain docs for using the Heroku CLI with a command like the following:

heroku drains:add [http|https]://HOSTNAME:PORT/heroku/api/v1/drain -a HEROKU_APP_NAME

You can specify multiple loki.source.heroku components by giving them different labels.

Usage

loki.source.heroku "<LABEL>" {
    http {
        listen_address = "<LISTEN_ADDRESS>"
        listen_port    = "<LISTEN_PORT>"
    }
    forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with loki.source.heroku:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`graceful_shutdown_timeout`	`duration`	Timeout for servers graceful shutdown. If configured, should be greater than zero.	`"30s"`	no
`labels`	`map(string)`	The labels to associate with each received Heroku record.	`{}`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no
`use_incoming_timestamp`	`bool`	Whether to use the timestamp received from Heroku.	`false`	no

Blocks

You can use the following blocks with loki.source.heroku:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`grpc`

The grpc block configures the gRPC server.

You can use the following arguments to configure the grpc block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`conn_limit`	`int`	Maximum number of simultaneous HTTP connections. Defaults to no limit.	`0`	no
`listen_address`	`string`	Network address on which the server listens for new connections. It defaults to accepting all incoming connections.	`""`	no
`listen_port`	`int`	Port number on which the server listens for new connections. Defaults to a random free port.	`0`	no
`max_connection_age_grace`	`duration`	An additive period after `max_connection_age` after which the connection is forcibly closed.	`"infinity"`	no
`max_connection_age`	`duration`	The duration for the maximum time a connection may exist before it’s closed.	`"infinity"`	no
`max_connection_idle`	`duration`	The duration after which an idle connection is closed.	`"infinity"`	no
`server_max_concurrent_streams`	`int`	Limit on the number of concurrent streams for gRPC calls (0 = unlimited).	`100`	no
`server_max_recv_msg_size`	`int`	Limit on the size of a gRPC message this server can receive (bytes).	`4MB`	no
`server_max_send_msg_size`	`int`	Limit on the size of a gRPC message this server can send (bytes).	`4MB`	no

`http`

The http block configures the HTTP server.

You can use the following arguments to configure the http block. Any omitted fields take their default values.

Name	Type	Description	Default	Required
`conn_limit`	`int`	Maximum number of simultaneous HTTP connections. Defaults to no limit.	`0`	no
`listen_address`	`string`	Network address on which the server listens for new connections. Defaults to accepting all incoming connections.	`""`	no
`listen_port`	`int`	Port number on which the server listens for new connections.	`8080`	no
`server_idle_timeout`	`duration`	Idle timeout for HTTP server.	`"120s"`	no
`server_read_timeout`	`duration`	Read timeout for HTTP server.	`"30s"`	no
`server_write_timeout`	`duration`	Write timeout for HTTP server.	`"30s"`	no

`tls`

The tls block configures TLS for the HTTP and gRPC servers.

Name	Type	Description	Default	Required
`cert_pem`	`string`	PEM data of the server TLS certificate.	`""`	no
`cert_file`	`string`	Path to the server TLS certificate on disk.	`""`	no
`client_auth_type`	`string`	Client authentication to use.	`"NoClientCert"`	no
`client_ca_file`	`string`	Path to the client CA file on disk to validate requests against.	`""`	no
`client_ca_pem`	`string`	PEM data of the client CA to validate requests against.	`""`	no
`key_file`	`string`	Path to the server TLS key on disk.	`""`	no
`key_pem`	`secret`	PEM data of the server TLS key.	`""`	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

Labels

The labels map is applied to every message that the component reads.

The following internal labels all prefixed with __ are available but are discarded if not relabeled:

__heroku_drain_app
__heroku_drain_host
__heroku_drain_log_id
__heroku_drain_proc

All URL query parameters are translated to __heroku_drain_param_<name>

If the X-Scope-OrgID header is set it’s translated to __tenant_id__

Exported fields

loki.source.heroku doesn’t export any fields.

Component health

loki.source.heroku is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.heroku exposes some debug information per Heroku listener:

Whether the listener is currently running.
The listen address.

Debug metrics

loki_source_heroku_drain_target_inflight_requests (gauge): Current number of inflight requests.
loki_source_heroku_drain_target_request_duration_seconds (histogram): HTTP request handling time, in seconds.
loki_source_heroku_drain_target_request_message_bytes (histogram): Request message size, in bytes.
loki_source_heroku_drain_target_response_message_bytes (histogram): Response message size, in bytes.
loki_source_heroku_drain_target_tcp_connections (gauge): Current number of accepted TCP connections.
loki_source_heroku_drain_entries_total (counter): Number of successful entries received by the Heroku target.
loki_source_heroku_drain_parsing_errors_total (counter): Number of parsing errors while receiving Heroku messages.

Example

This example listens for Heroku messages over TCP in the specified port and forwards them to a loki.write component using the Heroku timestamp.

loki.source.heroku "local" {
    http {
        listen_address = "0.0.0.0"
        listen_port    = 4040
    }
    use_incoming_timestamp = true
    labels                 = {component = "loki.source.heroku"}
    forward_to             = [loki.write.local.receiver]
}

loki.write "local" {
    endpoint {
        url = "loki:3100/api/v1/push"
    }
}

When using the default http block settings, the server listen for new connection on port 8080.

loki.source.heroku "local" {
    use_incoming_timestamp = true
    labels                 = {component = "loki.source.heroku"}
    forward_to             = [loki.write.local.receiver]
}

loki.write "local" {
    endpoint {
        url = "loki:3100/api/v1/push"
    }
}

Compatible components

loki.source.heroku can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.journal

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.journal`

loki.source.journal reads from the systemd journal and forwards them to other loki.* components.

You can specify multiple loki.source.journal components by giving them different labels.

Note
Make sure that the alloy user is a member of the following groups:

adm

systemd-journal

Usage

loki.source.journal "<LABEL>" {
  forward_to    = <RECEIVER_LIST>
}

Arguments

The component starts a journal reader and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.journal:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`format_as_json`	`bool`	Whether to forward the original journal entry as JSON.	`false`	no
`labels`	`map(string)`	The labels to apply to every log coming out of the journal.	`{}`	no
`matches`	`string`	Journal field matches to filter entries using systemd journal match syntax.	`""`	no
`max_age`	`duration`	The oldest relative time from process start that Alloy reads.	`"7h"`	no
`path`	`string`	Path to a directory to read entries from.	`""`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no

Note
Grafana Alloy adds a job label with the full name of the component loki.source.journal.LABEL.

When the format_as_json argument is true, log messages pass through as JSON with all of the original fields from the journal entry. Otherwise, Alloy takes the log message from the content of the MESSAGE field from the journal entry.

When the path argument is empty, Alloy uses /var/log/journal and /run/log/journal for discovering journal entries.

The relabel_rules argument can make use of the rules export value from a loki.relabel component to apply one or more relabeling rules to log entries before they’re forwarded to the list of receivers in forward_to.

All messages read from the journal include internal labels following the pattern of __journal_FIELDNAME and Alloy drops them before sending to the list of receivers specified in forward_to. To keep these labels, use the relabel_rules argument and relabel them to not have the __ prefix.

Note
Many field names from journald start with an _, such as _systemd_unit. The final internal label name would be __journal__systemd_unit, with two underscores between __journal and systemd_unit.

Additionally, the PRIORITY field receives special handling and creates two labels:

__journal_priority - The numeric priority value between 0 and 7

__journal_priority_keyword - The priority keyword, for example emerg, alert, crit, error, warning, notice, info, or debug

Journal matches

The matches argument filters journal entries using systemd journal field match syntax. Each match must be in the format FIELD=VALUE, where FIELD is a journal field name and VALUE is the exact value to match.

Multiple matches can exist in a single string separated by spaces. When you provide multiple matches, they work as a logical AND operation - all matches must satisfy for Alloy to include an entry.

Common journal fields

The most commonly used journal fields for filtering include:

_SYSTEMD_UNIT - The systemd unit name, for example, nginx.service
PRIORITY - The syslog priority level between 0 and 7, where 0 is highest priority
_PID - Process ID
_UID - User ID
_COMM - Command name
SYSLOG_IDENTIFIER - Syslog identifier
_TRANSPORT - Transport mechanism, for example, kernel, syslog, journal

For a complete list of available journal fields, refer to the systemd.journal-fields documentation.

Match syntax examples

"_SYSTEMD_UNIT=nginx.service" - Filter entries from nginx service only
"PRIORITY=3" - Filter entries with error priority level
"_SYSTEMD_UNIT=nginx.service PRIORITY=3" - Filter nginx errors only (logical AND)

Troubleshoot matches syntax

If the matches argument contains invalid syntax, Alloy reports the error Error parsing journal reader 'matches' configuration value. This typically occurs when:

A match is missing the = character, for example, "_SYSTEMD_UNIT nginx.service"
A match contains multiple = characters, for example, "FIELD=value=extra"
Field names or values contain spaces without proper handling

To resolve matches parsing errors, ensure each match follows the exact format FIELD=VALUE with no extra characters.

Note
The + character for logical OR operations that journalctl supports isn’t supported in the Alloy matches argument. Only logical AND filtering is available by specifying multiple space-separated matches.

Blocks

You can use the following blocks with loki.source.journal:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`legacy_position`

Name	Type	Description	Required
`file`	`string`	File to convert.	yes
`name`	`string`	Job name used for journal (agent static or promtail)	yes

The translation of legacy position file will happens if there is no position file already and is a valid yaml file to convert.

Component health

loki.source.journal is only reported as unhealthy if given an invalid configuration.

Debug Metrics

loki_source_journal_target_parsing_errors_total (counter): Total number of parsing errors while reading journal messages.
loki_source_journal_target_lines_total (counter): Total number of successful journal lines read.

Example

The following examples show how to use loki.source.journal in a basic configuration and in a configuration that filters specific services.

Basic configuration

loki.relabel "journal" {
  forward_to = []

  rule {
    source_labels = ["__journal__systemd_unit"]
    target_label  = "unit"
  }
}

loki.source.journal "read"  {
  forward_to    = [loki.write.endpoint.receiver]
  relabel_rules = loki.relabel.journal.rules
  labels        = {component = "loki.source.journal"}
}

loki.write "endpoint" {
  endpoint {
    url ="loki:3100/api/v1/push"
  }
}

Filter specific services with matches

// Read only entries from a specific systemd unit
loki.source.journal "nginx_logs" {
  forward_to = [loki.write.endpoint.receiver]
  matches    = "_SYSTEMD_UNIT=nginx.service"
  labels     = {service = "nginx"}
}

// Read entries from multiple conditions (logical AND)
loki.source.journal "critical_errors" {
  forward_to = [loki.write.endpoint.receiver]  
  matches    = "_SYSTEMD_UNIT=nginx.service PRIORITY=3"
  labels     = {service = "nginx", level = "error"}
}

// Read high-priority entries across all services
loki.source.journal "alerts" {
  forward_to = [loki.write.endpoint.receiver]
  matches    = "PRIORITY=0"
  labels     = {priority = "emergency"}
}

loki.write "endpoint" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.journal can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.kafka

Mon, 13 Apr 2026 07:37:47 +0000

loki.source.kafka

loki.source.kafka reads messages from Kafka using a consumer group and forwards them to other loki.* components.

The component starts a new Kafka consumer group for the given arguments and fans out incoming entries to the list of receivers in forward_to.

Before using loki.source.kafka, Kafka should have at least one producer writing events to at least one topic. Follow the steps in the Kafka Quick Start to get started with Kafka.

You can specify multiple loki.source.kafka components by giving them different labels.

Usage

loki.source.kafka "<LABEL>" {
  brokers    = "<BROKER_LIST>"
  topics     = "<TOPIC_LIST>"
  forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with loki.source.kafka:

Name	Type	Description	Default	Required
`brokers`	`list(string)`	The list of brokers to connect to Kafka.		yes
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`topics`	`list(string)`	The list of Kafka topics to consume.		yes
`assignor`	`string`	The consumer group rebalancing strategy to use.	`"range"`	no
`group_id`	`string`	The Kafka consumer group ID.	`"loki.source.kafka"`	no
`labels`	`map(string)`	The labels to associate with each received Kafka event.	`{}`	no
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no
`use_incoming_timestamp`	`bool`	Whether to use the timestamp received from Kafka.	`false`	no
`version`	`string`	Kafka version to connect to.	`"2.2.1"`	no

assignor values can be either "range", "roundrobin", or "sticky".

If a topic starts with a ‘^’, it’s treated as a regular expression and may match multiple topics.

Labels from the labels argument are applied to every message that the component reads.

In addition to custom labels, the following internal labels prefixed with __ are available:

__meta_kafka_group_id
__meta_kafka_member_id
__meta_kafka_message_key
__meta_kafka_message_offset
__meta_kafka_partition
__meta_kafka_topic

Blocks

You can use the following blocks with loki.source.kafka:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`authentication`

The authentication block defines the authentication method when communicating with the Kafka event brokers.

Name	Type	Description	Default	Required
`type`	`string`	Type of authentication.	`"none"`	no

type supports the values "none", "ssl", and "sasl". If "ssl" is used, you must set the tls_config block. If "sasl" is used, you must set the sasl_config block.

`sasl_config`

The sasl_config block defines the listen address and port where the listener expects Kafka messages to be sent to.

Name	Type	Description	Default	Required
`mechanism`	`string`	Specifies the SASL mechanism the client uses to authenticate with the broker.	`"PLAIN""`	no
`password`	`secret`	The password to use for SASL authentication.	`""`	no
`use_tls`	`bool`	If true, SASL authentication is executed over TLS.	`false`	no
`user`	`string`	The user name to use for SASL authentication.	`""`	no

`oauth_config`

The oauth_config is required when the SASL mechanism is set to OAUTHBEARER.

Name	Type	Description	Default	Required
`scopes`	`list(string)`	The scopes to set in the access token	`[]`	yes
`token_provider`	`string`	The OAuth 2.0 provider to be used. The only supported provider is `azure`.	`""`	yes

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

loki.source.kafka doesn’t export any fields.

Component health

loki.source.kafka is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.kafka doesn’t expose additional debug info.

Example

This example consumes Kafka events from the specified brokers and topics then forwards them to a loki.write component using the Kafka timestamp.

loki.source.kafka "local" {
  brokers                = ["localhost:9092"]
  topics                 = ["quickstart-events"]
  labels                 = {component = "loki.source.kafka"}
  forward_to             = [loki.write.local.receiver]
  use_incoming_timestamp = true
  relabel_rules          = loki.relabel.kafka.rules
}

loki.relabel "kafka" {
  forward_to      = [loki.write.local.receiver]

  rule {
    source_labels = ["__meta_kafka_topic"]
    target_label  = "topic"
  }
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.kafka can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.kubernetes

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.kubernetes`

loki.source.kubernetes tails logs from Kubernetes containers using the Kubernetes API.

Note
This component collects logs from Kubernetes Pods. You can’t use this component to collect logs from Kubernetes Nodes.

This component has the following benefits over loki.source.file:

It works without a privileged container.
It works without a root user.
It works without needing access to the filesystem of the Kubernetes node.
It doesn’t require a DaemonSet to collect logs, so one Alloy could collect logs for the whole cluster.

Note
Because loki.source.kubernetes uses the Kubernetes API to tail logs, it uses more network traffic and CPU consumption of Kubelets than loki.source.file.

You can specify multiple loki.source.kubernetes components by giving them different labels.

Usage

loki.source.kubernetes "<LABEL>" {
  targets    = <TARGET_LIST>
  forward_to = <RECEIVER_LIST>
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.kubernetes:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`targets`	`list(map(string))`	List of targets to tail logs from.		yes

Each target in targets must have the following labels:

__meta_kubernetes_namespace or __pod_namespace__ to specify the namespace of the Pod to tail.
__meta_kubernetes_pod_container_name or __pod_container_name__ to specify the container within the Pod to tail.
__meta_kubernetes_pod_name or __pod_name__ to specify the name of the Pod to tail.
__meta_kubernetes_pod_uid or __pod_uid__ to specify the UID of the Pod to tail.

By default, all of these labels are present when the output discovery.kubernetes is used.

A log tailer is started for each unique target in targets. Log tailers reconnect with exponential backoff to Kubernetes if the log stream returns before the container has permanently terminated.

Blocks

You can use the following blocks with loki.source.kubernetes:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`client`

The client block configures the Kubernetes client used to tail logs from containers. If the client block isn’t provided, the default in-cluster configuration with the service account of the running Alloy Pod is used.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][client] argument
[bearer_token][client] argument
[oauth2][oauth2] block

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`oauth2`

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Distribute log collection with other cluster nodes.		yes

When Alloy is using clustering, and enabled is set to true, then this loki.source.kubernetes component instance opts-in to participating in the cluster to distribute the load of log collection between all cluster nodes.

If Alloy is not running in clustered mode, then the block is a no-op and loki.source.kubernetes collects logs from every target it receives in its arguments.

Clustering looks only at the following labels for determining the shard key:

__meta_kubernetes_namespace
__meta_kubernetes_pod_container_name
__meta_kubernetes_pod_name
__meta_kubernetes_pod_uid
__pod_container_name__
__pod_name__
__pod_namespace__
__pod_uid__
container
job
namespace
pod

Exported fields

loki.source.kubernetes doesn’t export any fields.

Component health

loki.source.kubernetes is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.kubernetes exposes some target-level debug information per target:

The labels associated with the target.
The full set of labels which were found during service discovery.
The most recent time a log line was read and forwarded to the next components in the pipeline.
The most recent error from tailing, if any.

Debug metrics

loki.source.kubernetes doesn’t expose any component-specific debug metrics.

Example

This example collects logs from all Kubernetes Pods and forwards them to a loki.write component so they’re written to Loki.

discovery.kubernetes "pods" {
  role = "pod"
}

loki.source.kubernetes "pods" {
  targets    = discovery.kubernetes.pods.targets
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = sys.env("<LOKI_URL>")
  }
}

Compatible components

loki.source.kubernetes can accept arguments from the following components:

Components that export Targets
Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.kubernetes_events

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.kubernetes_events`

loki.source.kubernetes_events tails events from the Kubernetes API and converts them into log lines to forward to other loki components.

You can specify multiple loki.source.kubernetes_events components by giving them different labels.

Usage

loki.source.kubernetes_events "<LABEL>" {
  forward_to = <RECEIVER_LIST>
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.kubernetes_events:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`job_name`	`string`	Value to use for `job` label for generated logs.	`"loki.source.kubernetes_events"`	no
`log_format`	`string`	Format of the log.	`"logfmt"`	no
`namespaces`	`list(string)`	Namespaces to watch for Events in.	`[]`	no

By default, loki.source.kubernetes_events watches for events in all namespaces. A list of explicit namespaces to watch can be provided in the namespaces argument.

By default, the generated log lines are in the logfmt format. Use the log_format argument to change it to json. These formats are also names of LogQL parsers, which can be used for processing the logs.

Note
When watching all namespaces, Alloy must have permissions to watch events at the cluster scope (such as using a ClusterRoleBinding). If an explicit list of namespaces is provided, Alloy only needs permissions to watch events for those namespaces.

Log lines generated by loki.source.kubernetes_events have the following labels:

namespace: Namespace of the Kubernetes object involved in the event.
job: Value specified by the job_name argument.
instance: Value matching the component ID.

If job_name argument is the empty string, the component will fail to load. To remove the job label, forward the output of loki.source.kubernetes_events to a loki.relabel component.

For compatibility with the eventhandler integration from static mode, job_name can be set to "integrations/kubernetes/eventhandler".

Blocks

You can use the following blocks with loki.source.kubernetes_events:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`client`

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][client] argument
[bearer_token][client] argument
[oauth2][oauth2] block

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`oauth2`

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

loki.source.kubernetes_events doesn’t export any fields.

Component health

loki.source.kubernetes_events is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.kubernetes_events exposes the most recently read timestamp for events in each watched namespace.

Debug metrics

loki.source.kubernetes_events doesn’t expose any component-specific debug metrics.

Component behavior

The data path is inside the directory configured by the --storage.path command line argument.

Example

This example collects watches events in the kube-system namespace and forwards them to a loki.write component so they’re written to Loki.

loki.source.kubernetes_events "example" {
  // Only watch for events in the kube-system namespace.
  namespaces = ["kube-system"]

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = sys.env("LOKI_URL")
  }
}

Compatible components

loki.source.kubernetes_events can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.podlogs

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.podlogs`

loki.source.podlogs discovers PodLogs resources on Kubernetes. The PodLogs resources provide rules for which Kubernetes Pods to discover on your cluster.

loki.source.podlogs uses the Kubernetes API to tail the logs from the discovered Kubernetes Pods.

loki.source.podlogs is similar to loki.source.kubernetes, but uses custom resources rather than being fed targets from another component.

Note
Because loki.source.podlogs uses the Kubernetes API to tail logs, it uses more network traffic and CPU consumption of Kubelets than loki.source.file.

You can specify multiple loki.source.podlogs components by giving them different labels.

Usage

loki.source.podlogs "<LABEL>" {
  forward_to = <RECEIVER_LIST>
}

Arguments

The component starts a new reader for each of the given targets and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.podlogs:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`preserve_discovered_labels`	`bool`	Preserve discovered pod metadata labels for use by downstream components.	`false`	no
`tail_from_end`	`bool`	Start reading from the end of the log stream for newly discovered Pod containers.	`false`	no

loki.source.podlogs searches for PodLogs resources on Kubernetes. Each PodLogs resource describes a set of pods to tail logs from.

When tail_from_end is false (the default), loki.source.podlogs reads all available logs from the Kubernetes API for newly discovered Pod containers. For long-running Pods, this can result in a large volume of logs being processed, which may be rejected by the downstream Loki instance if they are too old. Set tail_from_end to true to only read new logs from the point of discovery, ignoring the historical log buffer. If a last-read offset is already saved for a Pod, loki.source.podlogs will resume from that position and ignore the tail_from_end argument.

When preserve_discovered_labels is true, loki.source.podlogs preserves discovered Pod metadata labels so they can be accessed by downstream components. This enables component chaining where discovered Pod metadata labels can be accessed by components like loki.relabel. The preserved labels include all the Pod metadata labels that are available for relabeling within PodLogs custom resources.

`PodLogs` custom resource

The PodLogs resource describes a set of Pods to collect logs from.

Note
loki.source.podlogs looks for PodLogs of monitoring.grafana.com/v1alpha2, and isn’t compatible with PodLogs from the Agent Operator, which are version v1alpha1.

Field	Type	Description
`apiVersion`	string	`monitoring.grafana.com/v1alpha2`
`kind`	string	`PodLogs`
`metadata`	ObjectMeta	Metadata for the PodLogs.
`spec`	PodLogsSpec	Definition of what Pods to collect logs from.

`PodLogsSpec`

PodLogsSpec describes a set of Pods to collect logs from.

Field	Type	Description
`selector`	LabelSelector	Label selector of Pods to collect logs from.
`namespaceSelector`	LabelSelector	Label selector of Namespaces that Pods can be discovered in.
`relabelings`	RelabelConfig	Relabel rules to apply to discovered Pods.

If selector is left as the default value, all Pods are discovered. If namespaceSelector is left as the default value, all Namespaces are used for Pod discovery.

The relabelings field can be used to modify labels from discovered Pods. The following meta labels are available for relabeling:

__meta_kubernetes_namespace: The namespace of the Pod.
__meta_kubernetes_pod_annotation_<annotationname>: Each annotation from the Pod.
__meta_kubernetes_pod_annotationpresent_<annotationname>: true for each annotation from the Pod.
__meta_kubernetes_pod_container_image: The image the container is using.
__meta_kubernetes_pod_container_init: true if the container is an InitContainer.
__meta_kubernetes_pod_container_name: Name of the container.
__meta_kubernetes_pod_controller_kind: Object kind of the Pod’s controller.
__meta_kubernetes_pod_controller_name: Name of the Pod’s controller.
__meta_kubernetes_pod_host_ip: The current host IP of the Pod object.
__meta_kubernetes_pod_ip: The Pod IP of the Pod.
__meta_kubernetes_pod_label_<labelname>: Each label from the Pod.
__meta_kubernetes_pod_labelpresent_<labelname>: true for each label from the Pod.
__meta_kubernetes_pod_name: The name of the Pod.
__meta_kubernetes_pod_node_name: The name of the node the Pod is scheduled onto.
__meta_kubernetes_pod_phase: Set to Pending, Running, Succeeded, Failed or Unknown in the lifecycle.
__meta_kubernetes_pod_ready: Set to true or false for the Pod’s ready state.
__meta_kubernetes_pod_uid: The UID of the Pod.

In addition to the meta labels, the following labels are exposed to tell loki.source.podlogs which container to tail:

__pod_container_name__: The container name within the Pod.
__pod_name__: The name of the Pod.
__pod_namespace__: The namespace of the Pod.
__pod_uid__: The UID of the Pod.

Blocks

You can use the following blocks with loki.source.podlogs:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`client`

The following arguments are supported:

Name	Type	Description	Default	Required
`api_server`	`string`	URL of the Kubernetes API server.		no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`kubeconfig_file`	`string`	Path of the `kubeconfig` file to use for connecting to Kubernetes.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth]block
[bearer_token_file][client] argument
[bearer_token][client] argument
[oauth2][oauth2] block

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`authorization`

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Distribute log collection with other cluster nodes.		yes

When Alloy is using clustering, and enabled is set to true, then this loki.source.podlogs component instance opts-in to participating in the cluster to distribute the load of log collection between all cluster nodes.

If Alloy is not running in clustered mode, then the block is a no-op and loki.source.podlogs collects logs based on every PodLogs resource discovered.

Clustering looks only at the following labels for determining the shard key:

__pod_namespace__
__pod_name__
__pod_container_name__
__pod_uid__
__meta_kubernetes_namespace
__meta_kubernetes_pod_name
__meta_kubernetes_pod_container_name
__meta_kubernetes_pod_uid
container
pod
job
namespace

`node_filter`

The node_filter block configures node-based filtering for Pod discovery.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	Enable node-based filtering for Pod discovery.	`false`	no
`node_name`	`string`	Node name to filter Pods by. Falls back to the `NODE_NAME` environment variable if empty.	`""`	no

When you set enabled to true, loki.source.podlogs only discovers and collects logs from Pods running on the specified node. This is particularly useful when running Alloy as a DaemonSet to avoid collecting logs from Pods on other nodes.

If you don’t specify node_name, loki.source.podlogs attempts to use the NODE_NAME environment variable. This allows for easy configuration in DaemonSet deployments where you can inject the node name with the Kubernetes downward API.

Example DaemonSet configuration:

env:
  - name: NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName

Node filtering significantly reduces API server load and network traffic by limiting Pod discovery to only the local node, making it highly recommended for DaemonSet deployments in large clusters.

`match_expression`

The match_expression block describes a Kubernetes label match expression for PodLogs or Namespace discovery.

The following arguments are supported:

Name	Type	Description	Required
`key`	`string`	The label name to match against.	yes
`operator`	`string`	The operator to use when matching.	yes
`values`	`list(string)`	The values used when matching.	no

The operator argument must be one of the following strings:

"In"
"NotIn"
"Exists"
"DoesNotExist"

Both selector and namespace_selector can make use of multiple match_expression inner blocks which are treated as AND clauses.

`oauth2`

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`selector` and `namespace_selector`

The selector and namespce_selector blocks describe a Kubernetes label selector for PodLogs or Namespace discovery.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_labels`	`map(string)`	Label keys and values used to discover resources.	`{}`	no

When the match_labels argument is empty, all resources are matched.

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

When preserve_discovered_labels is set to false, loki.source.podlogs doesn’t export any discovered fields (__meta labels).

When preserve_discovered_labels is set to true, loki.source.podlogs sends the discovered labels to the downstream components, and then the labels are dropped by either loki.process or loki.write when the pipeline is completed.

Component health

loki.source.podlogs is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.podlogs exposes some target-level debug information per target:

The labels associated with the target.
The full set of labels which were found during service discovery.
The most recent time a log line was read and forwarded to the next components in the pipeline.
The most recent error from tailing, if any.

Debug metrics

loki.source.podlogs doesn’t expose any component-specific debug metrics.

Example

This example discovers all PodLogs resources and forwards collected logs to a loki.write component so they’re written to Loki.

loki.source.podlogs "default" {
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = sys.env("LOKI_URL")
  }
}

This example shows how to preserve discovered Pod labels for use by downstream components:

loki.source.podlogs "with_label_preservation" {
  forward_to                  = [loki.write.local.receiver]
  preserve_discovered_labels  = true
}

loki.relabel "pod_relabeling" {
  forward_to = [loki.write.local.receiver]

  rule {
    source_labels = ["__meta_kubernetes_pod_label_app"]
    target_label  = "app"
  }

  rule {
    source_labels = ["__meta_kubernetes_pod_annotation_version"]
    target_label  = "version"
  }
}

loki.write "local" {
  endpoint {
    url = sys.env("LOKI_URL")
  }
}

This example shows how to use node filtering for DaemonSet deployments to collect logs only from Pods running on the current node:

loki.source.podlogs "daemonset" {
  forward_to = [loki.write.local.receiver]
  
  node_filter {
    enabled = true
    // node_name will be automatically read from NODE_NAME environment variable
  }
}

loki.write "local" {
  endpoint {
    url = sys.env("LOKI_URL")
  }
}

Compatible components

loki.source.podlogs can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.syslog

Mon, 13 Apr 2026 07:37:47 +0000

`loki.source.syslog`

loki.source.syslog listens for syslog messages over TCP or UDP connections and forwards them to other loki.* components. The messages must be compliant with the RFC5424 syslog protocol or the RFC3164 BSD syslog protocol. For a detailed example, refer to the Monitor RFC5424-compliant syslog messages with Grafana Alloy scenario.

Note
If your messages aren’t RFC5424 compliant, you can use raw syslog format in combination with the loki.process component.

Please note, that the raw syslog format is an experimental feature.

The component starts a new syslog listener for each of the given config blocks and fans out incoming entries to the list of receivers in forward_to.

You can specify multiple loki.source.syslog components by giving them different labels.

Usage

loki.source.syslog "<LABEL>" {
  listener {
    address = "<LISTEN_ADDRESS>"
  }
  ...

  forward_to = <RECEIVER_LIST>
}

Arguments

You can use the following arguments with loki.source.syslog:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`relabel_rules`	`RelabelRules`	Relabeling rules to apply on log entries.	`{}`	no

loki.source.syslog applies the following labels to log entries from the client information if possible.

__syslog_connection_ip_address
__syslog_connection_hostname

loki.source.syslog applies the following labels to log entries if they have been parsed from the syslog message.

__syslog_message_severity
__syslog_message_facility
__syslog_message_hostname
__syslog_message_app_name
__syslog_message_proc_id
__syslog_message_msg_id
__syslog_message_msg_counter
__syslog_message_sequence

If there is RFC5424 compliant structured data in the parsed message, it will be applied to the log entry as a label with prefix __syslog_message_sd_. For example, if the structured data provided is [example@99999 test="value"], the log entry will have the label __syslog_message_sd_example_99999_test with a value of value.

Before passing log entries to the next component in the pipeline, the syslog source will remove any labels with a __ prefix. To retain the __syslog_ labels on the log entries, you must use rules in the relabel_rules argument to move them to labels that do not have a __ prefix. The following relabel example retains all __syslog_ labels on the log entry when the entries are passed to the next component in the pipeline.

loki.relabel "syslog" {
  rule {
    action = "labelmap"
    regex = "__syslog_(.+)"
  }
}

Blocks

You can use the following blocks with loki.source.syslog:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`listener`

The listener block defines the listen address and protocol where the listener expects syslog messages to be sent to, as well as its behavior when receiving messages.

The following arguments can be used to configure a listener. Only the address field is required and any omitted fields take their default values.

Name	Type	Description	Default	Required
`address`	`string`	The `<host:port>` address to listen to for syslog messages.		yes
`idle_timeout`	`duration`	The idle timeout for TCP connections.	`"120s"`	no
`label_structured_data`	`bool`	Whether to translate syslog structured data to Loki labels.	`false`	no
`labels`	`map(string)`	The labels to associate with each received syslog record.	`{}`	no
`max_message_length`	`int`	The maximum limit to the length of syslog messages.	`8192`	no
`protocol`	`string`	The protocol to listen to for syslog messages. Must be either `tcp` or `udp`.	`"tcp"`	no
`rfc3164_default_to_current_year`	`bool`	Whether to default the incoming timestamp of an `rfc3164` message to the current year.	`false`	no
`rfc5424_allow_empty_msg`	`bool`	Whether to forward RFC5424 messages with empty MSG content. When `false`, such messages are dropped. Only applies when `syslog_format` is `rfc5424`.	`false`	no
`syslog_format`	`string`	The format for incoming messages. See supported formats.	`"rfc5424"`	no
`use_incoming_timestamp`	`bool`	Whether to set the timestamp to the incoming syslog record timestamp.	`false`	no
`use_rfc5424_message`	`bool`	Whether to forward the full RFC5424-formatted syslog message.	`false`	no

By default, the component assigns the log entry timestamp as the time it was processed.

The labels map is applied to every message that the component reads.

All header fields from the parsed RFC5424 messages are brought in as internal labels, prefixed with __syslog_.

If label_structured_data is set, structured data in the syslog header is also translated to internal labels in the form of __syslog_message_sd_<ID>_<KEY>. For example, a structured data entry of [example@99999 test="yes"] becomes the label __syslog_message_sd_example_99999_test with the value "yes".

The rfc3164_default_to_current_year argument is only relevant when use_incoming_timestamp is also set to true. rfc3164 message timestamps don’t contain a year, and this component’s default behavior is to mimic Promtail behavior and leave the year as 0. Setting rfc3164_default_to_current_year to true sets the year of the incoming timestamp to the current year using the local time of the Alloy instance.

Note
The rfc3164_default_to_current_year, use_incoming_timestamp and use_rfc5424_message fields cannot be used when syslog_format is set to raw.

Supported formats

rfc3164 A legacy syslog format, also known as BSD syslog. Example: <34>Oct 11 22:14:15 my-server-01 sshd[1234]: Failed password for root from 192.168.1.10 port 22 ssh2. loki.source.syslog drops messages with empty MSG content and increments the loki_source_syslog_empty_messages_total counter.
rfc5424 A modern, structured syslog format. Uses ISO 8601 for timestamps. Example: <165>1 2025-12-18T00:33:00Z web01 nginx - - [audit@123 id="456"] Login failed. loki.source.syslog drops messages with empty MSG content by default. Set rfc5424_allow_empty_msg to true to forward them. loki.source.syslog increments the loki_source_syslog_empty_messages_total counter in both cases for debugging.
raw Disables log line parsing. This format allows receiving non-RFC5424 compliant logs, such as CEF. Raw logs can be forwarded to loki.process component for parsing. loki.source.syslog drops messages with nil or empty body and increments the loki_source_syslog_empty_messages_total counter.

Note
The raw format is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

`raw_format_options`

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

The raw_format_options block configures the raw syslog format behavior.

Note
This block can only be used when you set syslog_format to raw.

The following argument is supported:

Name	Type	Description	Default	Required
`use_null_terminator_delimiter`	`bool`	Use null-terminator (`\0`) instead of line break (`\n`) to split log lines.	`false`	no

`rfc3164_cisco_components`

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

The rfc3164_cisco_components configures parsing of non-standard Cisco IOS syslog extensions.

Note
This block can only be used when you set syslog_format to rfc3164.

The following arguments are supported:

Name	Type	Description	Default	Required
`enable_all`	`bool`	Enables all components below.	`false`	no
`message_counter`	`bool`	Enables syslog message counter field parsing.	`false`	no
`sequence_number`	`bool`	Enables service sequence number field parsing.	`false`	no
`hostname`	`bool`	Enables origin hostname field parsing.	`false`	no
`second_fractions`	`bool`	Enables milliseconds parsing in timestamp field.	`false`	no

Note
At least one option has to be enabled if enable_all is set to false.

Caution
The rfc3164_cisco_components configuration must match your Cisco device configuration. The loki.source.syslog component cannot auto-detect which components are present because they share similar formats.

Cisco Device Configuration

conf t

! Enable message counter (on by default for remote logging)
logging host 10.0.0.10

! Add service sequence numbers
service sequence-numbers

! Add origin hostname
logging origin-id hostname

! Enable millisecond timestamps
service timestamps log datetime msec localtime

! Recommended: Enable NTP to remove asterisk
ntp server <your-ntp-server>

Current Limitations

Component Ordering: When Cisco components are selectively disabled on the device but the parser expects them, parsing will fail or produce incorrect results. Always match your parser configuration to your device configuration.
Structured Data: Messages with RFC5424-style structured data blocks (from logging host X session-id or sequence-num-session) are not currently supported. See the upstream issue for details.

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

Exported fields

loki.source.syslog doesn’t export any fields.

Component health

loki.source.syslog is only reported as unhealthy if given an invalid configuration.

Debug information

loki.source.syslog exposes some debug information per syslog listener:

Whether the listener is running.
The listen address.
The labels that the listener applies to incoming log entries.

Debug metrics

loki_source_syslog_empty_messages_total (counter): Total number of empty messages received from the syslog component.
loki_source_syslog_entries_total (counter): Total number of successful entries sent to the syslog component.
loki_source_syslog_parsing_errors_total (counter): Total number of parsing errors while receiving syslog messages.

Example

This example listens for syslog messages in valid RFC5424 format over TCP and UDP in the specified ports and forwards them to a loki.write component.

loki.source.syslog "local" {
  listener {
    address  = "127.0.0.1:51893"
    labels   = { component = "loki.source.syslog", protocol = "tcp" }
  }

  listener {
    address  = "127.0.0.1:51898"
    protocol = "udp"
    labels   = { component = "loki.source.syslog", protocol = "udp"}
  }

  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100/api/v1/push"
  }
}

Compatible components

loki.source.syslog can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.source.windowsevent

Mon, 30 Mar 2026 15:47:22 +0000

`loki.source.windowsevent`

loki.source.windowsevent reads events from Windows Event Logs and forwards them to other loki.* components.

You can specify multiple loki.source.windowsevent components by giving them different labels.

Usage

loki.source.windowsevent "<LABEL>" {
  eventlog_name = "<EVENTLOG_NAME>"
  forward_to    = <RECEIVER_LIST>
}

Arguments

The component starts a reader and fans out log entries to the list of receivers passed in forward_to.

You can use the following arguments with loki.source.windowsevent:

Name	Type	Description	Default	Required
`forward_to`	`list(LogsReceiver)`	List of receivers to send log entries to.		yes
`eventlog_name`	`string`	Event log to read from.		See below
`xpath_query`	`string`	XPath query to select events.	`"*"`	See below
`bookmark_path`	`string`	Keeps position in event log.	`"DATA_PATH/bookmark.xml"`	no
`exclude_event_data`	`bool`	Exclude event data.	`false`	no
`exclude_event_message`	`bool`	Exclude the human-friendly event message.	`false`	no
`exclude_user_data`	`bool`	Exclude user data.	`false`	no
`labels`	`map(string)`	The labels to associate with incoming logs.	`{}`	no
`locale`	`number`	Locale ID for event rendering. 0 default is Windows Locale.	`0`	no
`poll_interval`	`duration`	How often to poll the event log.	`"3s"`	no
`use_incoming_timestamp`	`bool`	When false, assigns the current timestamp to the log.	`false`	no

Note
eventlog_name is required if xpath_query doesn’t specify the event log. You can define xpath_query in short or XML form. When you use the XML form you can specify event_log in the xpath_query. If you use the short form, you must define eventlog_name.

Note
legacy_bookmark_path converts the legacy Grafana Agent Static bookmark to a Alloy bookmark, if bookmark_path doesn’t exist.

Blocks

The loki.source.windowsevent component doesn’t support any blocks. You can configure this component with arguments.

Component health

loki.source.windowsevent is only reported as unhealthy if given an invalid configuration.

Example

This example collects log entries from the Event Log specified in eventlog_name and forwards them to a loki.write component.

loki.source.windowsevent "application"  {
    eventlog_name = "Application"
    forward_to = [loki.write.endpoint.receiver]
}

loki.write "endpoint" {
    endpoint {
        url ="loki:3100/api/v1/push"
    }
}

Compatible components

loki.source.windowsevent can accept arguments from the following components:

Components that export Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki.write

Mon, 13 Apr 2026 07:37:47 +0000

`loki.write`

loki.write receives log entries from other loki components and sends them over the network using the Loki logproto format.

You can specify multiple loki.write components by giving them different labels.

Usage

loki.write "<LABEL>" {
  endpoint {
    url = "<REMOTE_WRITE_URL>"
  }
}

Arguments

You can use the following arguments with loki.write:

Name	Type	Description	Default	Required
`external_labels`	`map(string)`	Labels to add to logs sent over the network.	`{}`	no
`max_streams`	`int`	Maximum number of active streams.	`0` (no limit)	no

Blocks

You can use the following blocks with loki.write:

Block	Description	Required
`stage.cri`	Configures a pre-defined CRI-format pipeline.	no
`stage.decolorize`	Strips ANSI color codes from log lines.	no
`stage.docker`	Configures a pre-defined Docker log format pipeline.	no
`stage.drop`	Configures a `drop` processing stage.	no
`stage.eventlogmessage`	Extracts data from the Message field in the Windows Event Log.	no
`stage.geoip`	Configures a `geoip` processing stage.	no
`stage.json`	Configures a JSON processing stage.	no
`stage.label_drop`	Configures a `label_drop` processing stage.	no
`stage.label_keep`	Configures a `label_keep` processing stage.	no
`stage.labels`	Configures a `labels` processing stage.	no
`stage.limit`	Configures a `limit` processing stage.	no
`stage.logfmt`	Configures a `logfmt` processing stage.	no
`stage.luhn`	Configures a `luhn` processing stage.	no
`stage.match`	Configures a `match` processing stage.	no
`stage.metrics`	Configures a `metrics` stage.	no
`stage.multiline`	Configures a `multiline` processing stage.	no
`stage.output`	Configures an `output` processing stage.	no
`stage.pack`	Configures a `pack` processing stage.	no
`stage.pattern`	Configures a `pattern` processing stage.	no
`stage.regex`	Configures a `regex` processing stage.	no
`stage.replace`	Configures a `replace` processing stage.	no
`stage.sampling`	Configures a `sampling` processing stage.	no
`stage.static_labels`	Configures a `static_labels` processing stage.	no
`stage.structured_metadata`	Configures a structured metadata processing stage.	no
`stage.structured_metadata_drop`	Configures a `structured_metadata_drop` processing stage.	no
`stage.template`	Configures a `template` processing stage.	no
`stage.tenant`	Configures a `tenant` processing stage.	no
`stage.timestamp`	Configures a `timestamp` processing stage.	no
`stage.truncate`	Configures a `truncate` processing stage.	no
`stage.windowsevent`	Configures a `windowsevent` processing stage.	no

`endpoint`

The endpoint block describes a single location to send logs to. You can use multiple endpoint blocks to send logs to multiple locations.

The following arguments are supported:

Name	Type	Description	Default	Required
`url`	`string`	Full URL to send logs to.		yes
`batch_size`	`string`	Maximum batch size of logs to accumulate before sending.	`"1MiB"`	no
`batch_wait`	`duration`	Maximum amount of time to wait before sending a batch.	`"1s"`	no
`bearer_token_file`	`string`	File containing a bearer token to authenticate with.		no
`bearer_token`	`secret`	Bearer token to authenticate with.		no
`enable_http2`	`bool`	Whether HTTP2 is supported for requests.	`true`	no
`follow_redirects`	`bool`	Whether redirects returned by the server should be followed.	`true`	no
`http_headers`	`map(list(secret))`	Custom HTTP headers to be sent along with each request. The map key is the header name.		no
`headers`	`map(string)`	Extra headers to deliver with the request.		no
`max_backoff_period`	`duration`	Maximum backoff time between retries.	`"5m"`	no
`max_backoff_retries`	`int`	Maximum number of retries.	`10`	no
`min_backoff_period`	`duration`	Initial backoff time between retries.	`"500ms"`	no
`name`	`string`	Optional name to identify this endpoint with.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`remote_timeout`	`duration`	Timeout for requests made to the URL.	`"10s"`	no
`retry_on_http_429`	`bool`	Retry when an HTTP 429 status code is received.	`true`	no
`tenant_id`	`string`	The tenant ID used by default to push logs.		no

At most, one of the following can be provided:

[authorization][authorization] block
[basic_auth][basic_auth] block
[bearer_token_file][endpoint] argument
[bearer_token][endpoint] argument
[oauth2][oauth2] block

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

If no tenant_id is provided, the component assumes that the Loki instance at endpoint is running in single-tenant mode and no X-Scope-OrgID header is sent.

When multiple endpoint blocks are provided, the loki.write component creates a client for each. Received log entries are fanned-out to these endpoints in succession. That means that if one endpoint is bottlenecked, it may impact the rest.

Each endpoint has a queue of batches to be sent. The queue_config block can be used to customize the behavior of this queue.

Endpoints can be named for easier identification in debug metrics by using the name argument. If the name argument isn’t provided, a name is generated based on a hash of the endpoint settings.

The retry_on_http_429 argument specifies whether HTTP 429 status code responses should be treated as recoverable errors. Other HTTP 4xx status code responses are never considered recoverable errors. When retry_on_http_429 is enabled, the retry mechanism is governed by the backoff configuration specified through min_backoff_period, max_backoff_period and max_backoff_retries attributes.

`authorization`

Name	Type	Description	Required
`credentials_file`	`string`	File containing the secret value.	no
`credentials`	`secret`	Secret value.	no
`type`	`string`	Authorization type, for example, “Bearer”.	no

credential and credentials_file are mutually exclusive, and only one can be provided inside an authorization block.

Warning
Using credentials_file causes the file to be read on every outgoing request. Use the local.file component with the credentials attribute instead to avoid unnecessary reads.

`basic_auth`

Name	Type	Description	Required
`password_file`	`string`	File containing the basic auth password.	no
`password`	`secret`	Basic auth password.	no
`username`	`string`	Basic auth username.	no

password and password_file are mutually exclusive, and only one can be provided inside a basic_auth block.

Warning
Using password_file causes the file to be read on every outgoing request. Use the local.file component with the password attribute instead to avoid unnecessary reads.

`oauth2`

Name	Type	Description	Default	Required
`client_id`	`string`	OAuth2 client ID.		no
`client_secret_file`	`string`	File containing the OAuth2 client secret.		no
`client_secret`	`secret`	OAuth2 client secret.		no
`endpoint_params`	`map(string)`	Optional parameters to append to the token URL.		no
`no_proxy`	`string`	Comma-separated list of IP addresses, CIDR notations, and domain names to exclude from proxying.		no
`proxy_connect_header`	`map(list(secret))`	Specifies headers to send to proxies during CONNECT requests.		no
`proxy_from_environment`	`bool`	Use the proxy URL indicated by environment variables.	`false`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`scopes`	`list(string)`	List of scopes to authenticate with.		no
`token_url`	`string`	URL to fetch the token from.		no

client_secret and client_secret_file are mutually exclusive, and only one can be provided inside an oauth2 block.

Warning
Using client_secret_file causes the file to be read on every outgoing request. Use the local.file component with the client_secret attribute instead to avoid unnecessary reads.

The oauth2 block may also contain a separate tls_config sub-block.

no_proxy can contain IPs, CIDR notations, and domain names. IP and domain names can contain port numbers. proxy_url must be configured if no_proxy is configured.

proxy_connect_header should only be configured if proxy_url or proxy_from_environment are configured.

`queue_config`

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

The optional queue_config block configures how the endpoint queues batches of logs sent to Loki.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`bool`	If `true`, block until there is space in the queue; if `false`, drop entries when queue is full.	`true`	no
`capacity`	`string`	Controls the size of the underlying send queue buffer. This setting should be considered a worst-case scenario of memory consumption, in which all enqueued batches are full.	`10MiB`	no
`drain_timeout`	`duration`	Configures the maximum time the client can take to drain the send queue upon shutdown. During that time, it enqueues pending batches and drains the send queue sending each.	`"1m"`	no
`min_shards`	`number`	Minimum number of concurrent shards sending samples to the endpoint.	`1`	no

Each endpoint is divided into a number of concurrent shards which are responsible for sending a fraction of batches. The number of shards is controlled with min_shards argument. Each shard has a queue of batches it keeps in memory, controlled with the capacity argument.

Queue size is calculated using batch_size and capacity for each shard. So if batch_size is 1MiB and capacity is 10MiB each shard would be able to queue up 10 batches. The maximum amount of memory required for all configured shards can be calculated using capacity * min_shards.

`tls_config`

Name	Type	Description	Required
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.	no
`ca_file`	`string`	CA certificate to validate the server with.	no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.	no
`cert_file`	`string`	Certificate file for client authentication.	no
`insecure_skip_verify`	`bool`	Disables validation of the server certificate.	no
`key_file`	`string`	Key file for client authentication.	no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.	no
`min_version`	`string`	Minimum acceptable TLS version.	no
`server_name`	`string`	ServerName extension to indicate the name of the server.	no

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

ca_pem and ca_file
cert_pem and cert_file
key_pem and key_file

When configuring client authentication, both the client certificate (using cert_pem or cert_file) and the client key (using key_pem or key_file) must be provided.

"TLS10" (TLS 1.0)
"TLS11" (TLS 1.1)
"TLS12" (TLS 1.2)
"TLS13" (TLS 1.3)

`wal`

EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

The optional wal block configures the Write-Ahead Log (WAL) used in the Loki remote-write client. To enable the WAL, you must include the wal block in your configuration. When the WAL is enabled, the log entries sent to the loki.write component are first written to a WAL under the dir directory and then read into the remote-write client. This process provides durability guarantees when an entry reaches this component. The client knows when to read from the WAL using the following two mechanisms:

The WAL-writer side of the loki.write component notifies the reader side that new data is available.
The WAL-reader side periodically checks if there is new data, increasing the wait time exponentially between min_read_frequency and max_read_frequency.

The WAL is located inside a component-specific directory relative to the storage path Alloy is configured to use. Refer to the run documentation for more information about how to change the storage path.

The following arguments are supported:

Name	Type	Description	Default	Required
`drain_timeout`	`duration`	Maximum time the WAL drain procedure can take, before being forcefully stopped.	`"30s"`	no
`enabled`	`bool`	Whether to enable the WAL.	`false`	no
`max_read_frequency`	`duration`	Maximum backoff time in the backup read mechanism.	`"1s"`	no
`max_segment_age`	`duration`	Maximum time a WAL segment should be allowed to live. Segments older than this setting are eventually deleted.	`"1h"`	no
`min_read_frequency`	`duration`	Minimum backoff time in the backup read mechanism.	`"250ms"`	no

Exported fields

The following fields are exported and can be referenced by other components:

Name	Type	Description
`receiver`	`LogsReceiver`	A value that other components can use to send log entries to.

Component health

loki.write is only reported as unhealthy if given an invalid configuration.

Debug information

loki.write doesn’t expose any component-specific debug information.

Debug metrics

loki_write_batch_retries_total (counter): Number of times batches have had to be retried.
loki_write_dropped_bytes_total (counter): Number of bytes dropped because failed to be sent to the ingester after all retries.
loki_write_dropped_entries_total (counter): Number of log entries dropped because they failed to be sent to the ingester after all retries.
loki_write_sent_bytes_total (counter): Number of bytes sent.
loki_write_sent_entries_total (counter): Number of log entries sent to the ingester.
loki_write_request_size_bytes (histogram): Number of bytes for encoded requests.
loki_write_request_duration_seconds (histogram): Duration of sent requests.
loki_write_entry_propagation_latency_seconds (histogram): Time in seconds from entry creation until it’s either successfully sent or dropped.

Examples

The following examples show you how to create loki.write components that send log entries to different destinations.

Send log entries to a local Loki instance

You can create a loki.write component that sends your log entries to a local Loki instance:

loki.write "local" {
    endpoint {
        url = "http://loki:3100/loki/api/v1/push"
    }
}

Send log entries to a managed service

You can create a loki.write component that sends your log entries to a managed service, for example, Grafana Cloud. The Loki username and Grafana Cloud API Key are injected in this example through environment variables.

loki.write "default" {
    endpoint {
        url = "https://logs-xxx.grafana.net/loki/api/v1/push"
        basic_auth {
            username = sys.env("LOKI_USERNAME")
            password = sys.env("GRAFANA_CLOUD_API_KEY")
        }
    }
}

Technical details

loki.write uses snappy for compression.

Any labels that start with __ are removed before sending to the endpoint.

Compatible components

loki.write has exports that can be consumed by the following components:

Components that consume Loki LogsReceiver

Note
Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.

loki on Grafana Labs

loki.echo

loki.echo

Usage

Arguments

Blocks

Exported fields

Component health

Debug information

Example

Compatible components

loki.enrich

loki.enrich

Usage

Arguments

Blocks

Exports

Example

Component Behavior

Compatible components

loki.process

loki.process

Usage

Arguments

Blocks

stage.cri

stage.decolorize

stage.docker

stage.drop

stage.eventlogmessage

Example combined with stage.json

stage.geoip

GeoIP with City database example

GeoIP with ASN (Autonomous System Number) database example

GeoIP with Country database example

GeoIP with custom fields example

stage.json

stage.label_drop

stage.label_keep

stage.labels

stage.limit

stage.logfmt

stage.luhn

Example

Example with delimiters

stage.match

stage.metrics

metric.counter

metric.gauge

metric.histogram

metrics behavior

stage.multiline

stage.output

stage.pack

stage.pattern

stage.regex

stage.replace

stage.sampling

stage.static_labels

stage.structured_metadata

stage.structured_metadata_drop

stage.template

Supported functions

ToLower and ToUpper

Replace

Trim, TrimLeft, TrimRight, TrimSpace, TrimPrefix, TrimSuffix

regexReplaceAll and regexReplaceAllLiteral

Hash and Sha2Hash

stage.tenant

stage.timestamp

stage.truncate

rule

Example

stage.windowsevent

Example with loki.source.windowsevent

Exported fields

Component health

Debug information

Debug metrics

Example

`loki.echo`

`loki.enrich`

`loki.process`

`stage.cri`

`stage.decolorize`

`stage.docker`

`stage.drop`

`stage.eventlogmessage`

Example combined with `stage.json`

`stage.geoip`

`stage.json`

`stage.label_drop`

`stage.label_keep`

`stage.labels`

`stage.limit`

`stage.logfmt`

`stage.luhn`

Example with `delimiters`

`stage.match`

`stage.metrics`

`metric.counter`

`metric.gauge`

`metric.histogram`

`metrics` behavior

`stage.multiline`

`stage.output`

`stage.pack`

`stage.pattern`

`stage.regex`

`stage.replace`

`stage.sampling`

`stage.static_labels`

`stage.structured_metadata`

`stage.structured_metadata_drop`

`stage.template`

`ToLower` and `ToUpper`

`Replace`

`Trim`, `TrimLeft`, `TrimRight`, `TrimSpace`, `TrimPrefix`, `TrimSuffix`

`regexReplaceAll` and `regexReplaceAllLiteral`

`Hash` and `Sha2Hash`

`stage.tenant`

`stage.timestamp`

`stage.truncate`

`rule`

`stage.windowsevent`

Example with `loki.source.windowsevent`

`loki.relabel`

`rule`

`loki.rules.kubernetes`

`authorization`

`basic_auth`

`extra_query_matchers`

`matcher`

`rule_selector` and `rule_namespace_selector`

`match_expression`

`oauth2`

`tls_config`

`loki.secretfilter`

`loki.source.api`

`http`

`tls`

`loki.source.awsfirehose`

`http`

`tls`

`loki.source.azure_event_hubs`