HTTP Logger Configuration
Configuration reference for the HTTP Logger plugin (`http-logger`): the parameters and plugin metadata, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.
uri — string · required · since APISIX 1.4
URI of the HTTP(S) server.
auth_header — string · optional · since APISIX 1.4
Authorization headers, if required by the HTTP(S) server. The value is encrypted with AES before being stored in etcd.
timeout — integer · optional · default: 3 · since APISIX 1.4
Valid values: greater than 0
Time to keep the connection alive after sending a request.
log_format — object · optional · since APISIX 3.2.0
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 http-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 the example for more details.
log_format_extra — object · optional · since APISIX 3.18.0 · API7 Gateway 3.9.15
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.
include_req_body — boolean · optional · default: false · since APISIX 1.4
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.
include_req_body_expr — array[array] · optional · since APISIX 3.8.0
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.
include_resp_body — boolean · optional · default: false · since APISIX 2.12.0
If true, include the response body in the log.
include_resp_body_expr — array[array] · optional · since APISIX 2.12.0
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.
max_req_body_bytes — integer · optional · default: 524288 · since APISIX 3.16.0 · API7 Gateway 3.10.3
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.
max_resp_body_bytes — integer · optional · default: 524288 · since APISIX 3.16.0 · API7 Gateway 3.10.3
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.
concat_method — string · optional · default: json · since APISIX 2.0
Valid values: json or new_line
Method to concatenate logs. When set to json, use json.encode for all pending logs. When set to new_line, also use json.encode but use the newline character \n to concatenate lines.
ssl_verify — boolean · optional · default: false · since APISIX 2.13.0
If true, verify the server's SSL certificate.
name — string · optional · default: http logger · since APISIX 1.4 · API7 Gateway 3.8.6
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.
batch_max_size — integer · optional · default: 1000 · since APISIX 1.4 · API7 Gateway 3.8.6
Valid values: greater than 0
Number of log entries allowed in one batch. Once reached, the batch is sent to the logging service. Setting this parameter to 1 enables immediate processing.
inactive_timeout — integer · optional · default: 5 · since APISIX 1.4 · API7 Gateway 3.8.6
Valid values: greater than 0
Maximum time in seconds to wait for new logs before sending the batch. The value should be smaller than buffer_duration.
buffer_duration — integer · optional · default: 60 · since APISIX 1.4 · API7 Gateway 3.8.6
Valid values: greater than 0
Maximum time in seconds from the earliest entry before sending the batch.
retry_delay — integer · optional · default: 1 · since APISIX 1.4 · API7 Gateway 3.8.6
Valid values: greater than or equal to 0
Time in seconds to wait before retrying a failed batch.
max_retry_count — integer · optional · default: 0 · since APISIX 1.4 · API7 Gateway 3.8.6
Valid values: greater than or equal to 0
Maximum number of unsuccessful retries before dropping the log entries.
Plugin Metadata
log_format — object · optional · since APISIX 2.0
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.
log_format_extra — object · optional · since APISIX 3.18.0 · API7 Gateway 3.9.15
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.
max_pending_entries — integer · optional · default: 8192 in APISIX 3.18.0 and in API7 Enterprise 3.9.19 and 3.10.6; none in API7 Enterprise 3.9.18 and 3.10.5 · since APISIX 3.15.0 · API7 Gateway 3.8.17
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.