Skip to main content
API7.ai Logo

Parameters​

See plugin common configurations 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 field.

      In API7 Enterprise from version 3.8.0 and APISIX from version 3.17.0, index supports the configuration of built-in variables and a lua time format 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.

    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, 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 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. 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 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, 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]

    An array of one or more conditions in the form of APISIX expressions. 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

    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. 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 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​

  • log_format

    object

    Custom log format using key-value pairs in JSON format. Values can reference built-in variables.

    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. 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` in APISIX 3.18.0; none in API7 Enterprise 3.9.18 and 3.10.5

    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. 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 for sizing and verification guidance.