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
:
Blocks
You can use the following blocks with loki.write
:
The > symbol indicates deeper levels of nesting.
For example, endpoint
> basic_auth
refers to a basic_auth
block defined inside an endpoint
block.
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:
At most, one of the following can be provided:
authorization
blockbasic_auth
blockbearer_token_file
argumentbearer_token
argumentoauth2
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.
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 clients in succession.
That means that if one client is bottlenecked, it may impact the rest.
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
credential
and credentials_file
are mutually exclusive, and only one can be provided inside an authorization
block.
basic_auth
password
and password_file
are mutually exclusive, and only one can be provided inside a basic_auth
block.
oauth2
client_secret
and client_secret_file
are mutually exclusive, and only one can be provided inside an oauth2
block.
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.
queue_config
EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. The
stability.level
flag must be set toexperimental
to use the feature.
The optional queue_config
block configures, when WAL is enabled, how the underlying client queues batches of logs sent to Loki.
Refer to Write-Ahead block for more information.
The following arguments are supported:
tls_config
The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:
ca_pem
andca_file
cert_pem
andcert_file
key_pem
andkey_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)
wal
EXPERIMENTAL: This is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. The
stability.level
flag must be set toexperimental
to use the feature.
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
andmax_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:
Exported fields
The following fields are exported and can be referenced by other components:
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_encoded_bytes_total
(counter): Number of bytes encoded and ready to send.loki_write_request_duration_seconds
(histogram): Duration of sent requests.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_stream_lag_seconds
(gauge): Difference between current time and last batch timestamp for successful sends.
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.