# Elasticsearch Logger Configuration The `elasticsearch-logger` plugin sends gateway request and response logs to Elasticsearch in batches and supports customizable log formats and index names. Configuration covers plugin parameters and plugin metadata. ## Parameters[​](#parameters "Direct link to Parameters") See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) for configuration options available to all plugins. * endpoint\_addr string *** Deprecated. Use `endpoint_addrs` instead. Elasticsearch API endpoint address. Configure either `endpoint_addr` or `endpoint_addrs`. * endpoint\_addrs array\[string] *** Elasticsearch API endpoint addresses. If multiple endpoints are configured, one is selected randomly for each write. Configure either `endpoint_addrs` or the deprecated `endpoint_addr`. * field object required *** Elasticsearch field configurations. * index string required *** Elasticsearch [`_index`](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-index-field.html#mapping-index-field) field. In API7 Enterprise from version 3.8.0 and APISIX from version 3.17.0, `index` supports the configuration of [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md) and a [lua time format](https://www.lua.org/pil/22.1.html) in curly brackets to include the current date, such as `service-$host-{%Y-%m-%d}`. * log\_format object *** Custom log format using key-value pairs in JSON format. Values can reference [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md). If `include_req_body` or `include_resp_body` is true, reference `$request_body` or `$resp_body` to add the collected body to the custom log entry. The options do not add body fields to a custom format automatically. 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](https://docs.api7.ai/apisix/key-concepts/plugin-metadata.md), which configures the log format for all `elasticsearch-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](https://docs.api7.ai/hub/elasticsearch-logger.md#log-request-and-response-headers-with-plugin-metadata) for more details. * log\_format\_extra object *** Additional fields to add to the default log entry, using key-value pairs in JSON format. Values can reference [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md). 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. * auth object *** Elasticsearch user authentication configurations. * username string *** Elasticsearch authentication username. * password string *** Elasticsearch authentication password. The value is encrypted before being stored. * headers object *** Custom HTTP request headers to include in requests sent to Elasticsearch, as key-value pairs. They can complement or replace `auth` for authentication and other purposes. Introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.16.0. Header-value encryption was introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0. The values are [encrypted before storage](https://docs.api7.ai/apisix/production/security/data-encryption-with-keyring.md) 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. * ssl\_verify boolean default: `true` *** If true, perform SSL verification. * timeout integer default: `10` *** Elasticsearch send data timeout in seconds. * include\_req\_body boolean default: `false` *** If true, collect and include the request body in the default log fields. Request bodies buffered in memory or a temporary file can be logged, and `max_req_body_bytes` limits the logged body size. * include\_req\_body\_expr array\[array] *** An array of one or more conditions in the form of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions.md). When `include_req_body` is true, the expressions control proactive body reading and the `request.body` field in the default log format. A custom `log_format` or `log_format_extra` field that references `$request_body` can still include a body already buffered by NGINX when the expressions evaluate to false. Do not use this option as a data-redaction boundary. * include\_resp\_body boolean default: `false` *** If true, include the response body in the log. * include\_resp\_body\_expr array\[array] *** An array of one or more conditions in the form of [APISIX expressions](https://docs.api7.ai/apisix/reference/apisix-expressions.md). 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 default: `524288` vaild vaule: 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 default: `524288` vaild vaule: 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. * name string default: `elasticsearch-logger` *** Unique identifier of the plugin for the batch processor. If you use [Prometheus](https://docs.api7.ai/hub/prometheus.md) to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. * batch\_max\_size integer default: `1000` vaild vaule: greater than 0 *** Number of log entries allowed in one batch. Once reached, the batch is sent to Elasticsearch. Setting this parameter to 1 enables immediate processing. * inactive\_timeout integer default: `5` vaild vaule: 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 default: `60` vaild vaule: greater than 0 *** Maximum time in seconds from the earliest entry before sending the batch. * retry\_delay integer default: `1` vaild vaule: greater than or equal to 0 *** Time in seconds to wait before retrying a failed batch. * max\_retry\_count integer default: `0` vaild vaule: greater than or equal to 0 *** Maximum number of unsuccessful retries before dropping the log entries. ## Plugin Metadata[​](#plugin-metadata "Direct link to Plugin Metadata") * log\_format object *** Custom log format using key-value pairs in JSON format. Values can reference [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md). 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 *** Additional fields to add to the default log entry, using key-value pairs in JSON format. Values can reference [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md). 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 default: `8192` vaild vaule: 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](https://docs.api7.ai/apisix/reference/batch-processor.md#configure-the-pending-entry-limit) for sizing and verification guidance.