Loki Logger Configuration

Loki API base URLs, such as http://127.0.0.1:3100. If multiple endpoints are configured, the log will be pushed to a randomly determined endpoint from the list.

URI path to the Loki ingest endpoint.

Loki tenant ID. According to Loki's multi-tenancy documentation, the default value is set to fake under single-tenancy.

Key-value pairs of request headers, such as the Authorization header for non-local Loki services. The parameter cannot set X-Scope-OrgID or Content-Type. Introduced in API7 Enterprise 3.9.0. Header-value encryption was introduced in API7 Enterprise 3.9.18 and 3.10.5, and APISIX 3.18.0. The values are encrypted before storage (opens in Apache APISIX docs) when data encryption is enabled. Authorized Admin API GET requests return the complete decrypted header object; encryption at rest does not redact header names or values from API responses.

Loki log label. Support built-in variables (opens in Apache APISIX docs) and constant strings in values. Variables should be prefixed with a $ sign. For example, the label can be {"origin" = "apisix"} or {"origin" = "$remote_addr"}.

If true, verify Loki's SSL certificates.

Valid values: between 1 and 60000 inclusive

Timeout for the Loki service HTTP call in milliseconds.

If true, keep the connection alive for multiple requests.

Valid values: greater than or equal to 1000

Keepalive timeout in milliseconds.

Valid values: greater than or equal to 1

Maximum number of connections in the connection pool.

Custom log format using key-value pairs in JSON format. Values can reference built-in variables (opens in Apache APISIX docs).

In APISIX from 3.15.0, log format nested structures are supported up to five levels deep. In API7 Enterprise, only flat key-value structures are supported; nested structures are not yet supported.

You can also configure log format on a global scale using the plugin metadata (opens in Apache APISIX docs), which configures the log format for all loki-logger plugin instances. If the log format configured on the individual plugin instance differs from the log format configured on plugin metadata, the log format configured on the individual plugin instance takes precedence. See this example for more details.

Additional fields to add to the default log entry, using key-value pairs in JSON format. Values can reference built-in variables (opens in Apache APISIX docs). A configured field does not overwrite an existing default field. A plugin instance takes precedence over plugin metadata; setting an empty object on the instance disables the metadata value. When log_format is configured, log_format_extra is ignored. Introduced in API7 Enterprise 3.9.15 and 3.10.2, and APISIX 3.18.0.

Unique identifier of the plugin for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in apisix_batch_process_entries.

If true, include the request body in the log. Note that if the request body is too big to be kept in the memory, it can not be logged due to NGINX's limitations.

An array of one or more conditions in the form of APISIX expressions (opens in Apache APISIX docs). Used when the include_req_body is true. Request body would only be logged when the expressions configured here evaluate to true.

If true, include the response body in the log.

An array of one or more conditions in the form of APISIX expressions (opens in Apache APISIX docs). Used when the include_resp_body is true. Response body would only be logged when the expressions configured here evaluate to true.

Valid values: greater than or equal to 1

Maximum request body size in bytes to include in the log. If the request body exceeds this value, it will be truncated. Available in APISIX from 3.16.0.

Valid values: greater than or equal to 1

Maximum response body size in bytes to include in the log. If the response body exceeds this value, it will be truncated. Available in APISIX from 3.16.0.

Valid values: greater than 0

The number of log entries allowed in one batch. Once reached, the batch will be sent to the logging service. Setting this parameter to 1 means immediate processing.

Valid values: greater than 0

The maximum time in seconds to wait for new logs before sending the batch to the logging service. The value should be smaller than buffer_duration.

Valid values: greater than 0

The maximum time in seconds from the earliest entry allowed before sending the batch to the logging service.

Valid values: greater than or equal to 0

The time interval in seconds to retry sending the batch to the logging service if the batch was not successfully sent.

Valid values: greater than or equal to 0

The maximum number of unsuccessful retries allowed before dropping the log entries.

Custom log format using key-value pairs in JSON format. Values can reference built-in variables (opens in Apache APISIX docs).

In APISIX from 3.15.0, log format nested structures are supported up to five levels deep. In API7 Enterprise, only flat key-value structures are supported; nested structures are not yet supported.

Additional fields to add to the default log entry, using key-value pairs in JSON format. Values can reference built-in variables (opens in Apache APISIX docs). A configured field does not overwrite an existing default field. A plugin instance takes precedence over plugin metadata; setting an empty object on the instance disables the metadata value. When log_format is configured, log_format_extra is ignored. Introduced in API7 Enterprise 3.9.15 and 3.10.2, and APISIX 3.18.0.

Valid values: greater than or equal to 1

Maximum number of entries waiting in the batch processor. New entries are discarded when the backlog reaches the limit.

Introduced in API7 Enterprise 3.8.17 and APISIX 3.15.0.

The default changed to 8192 in APISIX 3.18.0 and in API7 Enterprise 3.9.19 on the 3.9 line and 3.10.6 on the 3.10 line. In API7 Enterprise 3.9.18 and 3.10.5, and in earlier APISIX versions, omitting the parameter leaves the backlog unlimited.

See Batch Processor (opens in Apache APISIX docs) for sizing and verification guidance.