# Log with Elasticsearch

[Elasticsearch](https://www.elastic.co/elasticsearch) is a popular JSON-based datastore for storing and indexing large volumes of data. It is often used to store logs from various sources and works with tools like [Logstash](https://www.elastic.co/logstash) and [Kibana](https://www.elastic.co/kibana) to form an entire observability stack known as the Elastic (ELK) Stack.

APISIX supports forwarding its logs directly to Elasticsearch through the [`elasticsearch-logger`](https://docs.api7.ai/hub/elasticsearch-logger.md) plugin. These logs can then be searched, filtered, and visualized through Kibana to gather insights to manage applications.

This guide will show you how to enable the [`elasticsearch-logger`](https://docs.api7.ai/hub/elasticsearch-logger.md) plugin to integrate APISIX with the ELK stack for observability.

## Prerequisite(s)[​](#prerequisites "Direct link to Prerequisite(s)")

* Install [Docker](https://docs.docker.com/get-docker/).
* Install [cURL](https://curl.se/) to send requests to the services for validation.
* Follow the [Getting Started tutorial](https://docs.api7.ai/apisix/getting-started.md) to start a new APISIX instance in Docker.
* If you use the Admin API examples and authentication is enabled, export an admin-role key as `ADMIN_API_KEY`. Configure the key under `deployment.admin.admin_key`. The Docker quickstart disables authentication for local evaluation; keep it enabled in production.

## Start Elasticsearch and Kibana[​](#start-elasticsearch-and-kibana "Direct link to Start Elasticsearch and Kibana")

Set passwords for the built-in Elasticsearch users used in this local example:

```
export ELASTIC_PASSWORD="apisix-elastic-pass"

export KIBANA_SYSTEM_PASSWORD="apisix-kibana-pass"
```

Create a data volume and start Elasticsearch with authentication enabled:

```
docker volume create apisix-quickstart-elasticsearch-data



docker run -d --name apisix-quickstart-elasticsearch \

  --network apisix-quickstart-net \

  -p 9200:9200 \

  -e discovery.type=single-node \

  -e xpack.security.enabled=true \

  -e xpack.security.http.ssl.enabled=false \

  -e ELASTIC_PASSWORD="${ELASTIC_PASSWORD}" \

  -e ES_JAVA_OPTS="-Xms512m -Xmx512m" \

  -v apisix-quickstart-elasticsearch-data:/usr/share/elasticsearch/data \

  docker.elastic.co/elasticsearch/elasticsearch:9.4.2
```

❶ Attach Elasticsearch to the APISIX quickstart network so that APISIX and Kibana can reach it by container name.

❷ Disable HTTP TLS only for this isolated local example. In production, use HTTPS endpoints and keep the plugin's `ssl_verify` option enabled so that APISIX verifies the Elasticsearch certificate.

❸ Persist Elasticsearch data in the named Docker volume created above.

Wait up to two minutes for Elasticsearch to start, then verify that authentication succeeds:

```
curl --fail --silent --show-error \

  --user "elastic:${ELASTIC_PASSWORD}" \

  --retry 24 \

  --retry-delay 5 \

  --retry-connrefused \

  --retry-max-time 120 \

  --max-time 5 \

  --output /dev/null \

  "http://127.0.0.1:9200"
```

Set the password Kibana uses to connect to Elasticsearch:

```
curl -fsS -u "elastic:${ELASTIC_PASSWORD}" \

  "http://127.0.0.1:9200/_security/user/kibana_system/_password" \

  -X POST \

  -H "Content-Type: application/json" \

  --data-binary @- <<EOF

{

  "password": "${KIBANA_SYSTEM_PASSWORD}"

}

EOF
```

Create a data volume and start the matching Kibana version:

```
docker volume create apisix-quickstart-kibana-data



docker run -d --name apisix-quickstart-kibana \

  --network apisix-quickstart-net \

  -p 5601:5601 \

  -e ELASTICSEARCH_HOSTS="http://apisix-quickstart-elasticsearch:9200" \

  -e ELASTICSEARCH_USERNAME="kibana_system" \

  -e ELASTICSEARCH_PASSWORD="${KIBANA_SYSTEM_PASSWORD}" \

  -v apisix-quickstart-kibana-data:/usr/share/kibana/data \

  docker.elastic.co/kibana/kibana:9.4.2
```

## Enable `elasticsearch-logger` Plugin[​](#enable-elasticsearch-logger-plugin "Direct link to enable-elasticsearch-logger-plugin")

Enable `elasticsearch-logger` globally and create a sample route to generate logs. Alternatively, you can enable the plugin on a route.

* Admin API
* ADC

Enable the `elasticsearch-logger` plugin on all routes:

```
curl "http://127.0.0.1:9180/apisix/admin/global_rules/elasticsearch" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -H "Content-Type: application/json" \

  --data-binary @- <<EOF

{

  "plugins": {

    "elasticsearch-logger": {

      "endpoint_addrs": [

        "http://apisix-quickstart-elasticsearch:9200"

      ],

      "field": {

        "index": "gateway-{%Y.%m.%d}"

      },

      "auth": {

        "username": "elastic",

        "password": "${ELASTIC_PASSWORD}"

      },

      "timeout": 60,

      "retry_delay": 1,

      "buffer_duration": 60,

      "max_retry_count": 0,

      "batch_max_size": 5,

      "inactive_timeout": 5

    }

  }

}

EOF
```

❶ Create a daily index by resolving the date expression, for example, to `gateway-2026.07.21`.

Create a sample route. Setting `pass_host` to `node` sends the upstream hostname in the `Host` header:

```
curl "http://127.0.0.1:9180/apisix/admin/routes/observability-logs" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "uri": "/get",

    "upstream": {

      "type": "roundrobin",

      "pass_host": "node",

      "nodes": {

        "postman-echo.com:80": 1

      }

    }

  }'
```

ADC exports global rules as one map keyed by plugin name. That export does not keep the original rule ID or which plugins shared a rule. If more than one rule configures the same plugin, the export keeps only one configuration. Use the Admin API tab in this section when you need to keep the original rule ID or grouping.

Export the current global rules:

```
adc dump -o adc-global-rules.yaml \

  --include-resource-type global_rule
```

caution

ADC dumps can contain decrypted sensitive fields returned by the Admin API. Restrict access to exported files and delete them after completing the change.

Edit the exported file to add the Elasticsearch logger while preserving every other plugin entry:

adc-global-rules.yaml (global\_rules excerpt)

```
global_rules:

  # Keep every other global plugin entry from the exported file.

  elasticsearch-logger:

    endpoint_addrs:

      - http://apisix-quickstart-elasticsearch:9200

    field:

      index: gateway-{%Y.%m.%d}

    auth:

      username: elastic

      password: apisix-elastic-pass

    timeout: 60

    retry_delay: 1

    buffer_duration: 60

    max_retry_count: 0

    batch_max_size: 5

    inactive_timeout: 5
```

Create the sample service in a separate file:

adc-service.yaml

```
services:

  - name: postman-echo

    labels:

      docs-example: elasticsearch

    routes:

      - name: observability-logs

        uris:

          - /get

    upstream:

      type: roundrobin

      pass_host: node

      nodes:

        - host: postman-echo.com

          port: 80

          weight: 1
```

❶ Create a daily index by resolving the date expression, for example, to `gateway-2026.07.21`.

Preview the global rules and confirm that the diff contains no unrelated plugin changes or deletions:

```
adc diff -f adc-global-rules.yaml \

  --include-resource-type global_rule
```

Preview the service-owned resources:

```
adc diff -f adc-service.yaml \

  --include-resource-type service \

  --label-selector docs-example=elasticsearch
```

Synchronize the reviewed global rules and service:

```
adc sync -f adc-global-rules.yaml \

  --include-resource-type global_rule



adc sync -f adc-service.yaml \

  --include-resource-type service \

  --label-selector docs-example=elasticsearch
```

## Customize Log Format[​](#customize-log-format "Direct link to Customize Log Format")

Customize the log format for `elasticsearch-logger` before generating traffic. The log format of most APISIX logging plugins can be customized locally on the plugin (e.g. bound to a route) and/or globally with [plugin metadata](https://docs.api7.ai/apisix/key-concepts/plugin-metadata.md).

Add host address, timestamp, and client IP address to the logs with [built-in variables](https://docs.api7.ai/apisix/reference/built-in-variables.md):

* Admin API
* ADC

```
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/elasticsearch-logger" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -H "Content-Type: application/json" \

  --data-binary @- <<'EOF'

{

  "log_format": {

    "host": "$host",

    "timestamp": "$time_iso8601",

    "client_ip": "$remote_addr"

  }

}

EOF
```

Export the complete plugin-metadata collection:

```
adc dump -o adc-plugin-metadata.yaml \

  --include-resource-type plugin_metadata
```

caution

ADC dumps can contain decrypted sensitive fields returned by the Admin API. Restrict access to exported files and delete them after completing the change.

Edit the exported file to add the Elasticsearch logger format while preserving metadata for every other plugin:

adc-plugin-metadata.yaml (plugin\_metadata excerpt)

```
plugin_metadata:

  # Keep all other plugin metadata from the exported file.

  elasticsearch-logger:

    log_format:

      host: $host

      timestamp: $time_iso8601

      client_ip: $remote_addr
```

Preview the complete metadata collection and confirm that no unrelated metadata changes are included:

```
adc diff -f adc-plugin-metadata.yaml \

  --include-resource-type plugin_metadata
```

Synchronize the reviewed plugin metadata:

```
adc sync -f adc-plugin-metadata.yaml \

  --include-resource-type plugin_metadata
```

## Configure Kibana[​](#configure-kibana "Direct link to Configure Kibana")

Send ten requests, then allow the inactive buffer to flush to Elasticsearch:

```
for i in {1..10}; do

  curl -sS "http://127.0.0.1:9080/get" > /dev/null

done



sleep 6
```

List the date-based indices:

```
curl -u "elastic:${ELASTIC_PASSWORD}" \

  "http://127.0.0.1:9200/_cat/indices/gateway-*?v"
```

You should see a `gateway-YYYY.MM.DD` index with documents. Inspect one indexed document:

```
curl -u "elastic:${ELASTIC_PASSWORD}" \

  "http://127.0.0.1:9200/gateway-*/_search?pretty&size=1"
```

The document `_source` should contain `host`, `timestamp`, and `client_ip` fields.

## View Logs in Kibana[​](#view-logs-in-kibana "Direct link to View Logs in Kibana")

Open [Kibana](http://127.0.0.1:5601) and sign in as `elastic` with the password stored in `ELASTIC_PASSWORD`.

Go to **Stack Management > Data Views**, select **Create data view**, and configure these values:

* **Name**: `APISIX logs`
* **Index pattern**: `gateway-*`
* **Timestamp field**: `timestamp`

![Kibana data view form configured for APISIX gateway indices](https://static.api7.ai/uploads/2026/07/24/sBMZnmKD_kibana-create-data-view.png)

Select **Save data view to Kibana**, then go to **Discover** and select the `APISIX logs` data view. The indexed gateway requests should be available for searching and filtering.

![Kibana Discover showing APISIX log documents from Elasticsearch](https://static.api7.ai/uploads/2026/07/24/3kGbggIG_kibana-discover-apisix-logs.png)

## Next Steps[​](#next-steps "Direct link to Next Steps")

See [`elasticsearch-logger`](https://docs.api7.ai/hub/elasticsearch-logger.md) plugin reference to learn more about the plugin configuration options.
