使用 Elasticsearch 记录日志

Elasticsearch 是一种常用的、基于 JSON 的数据存储，可用于保存和索引大量数据。它经常用于保存来自不同来源的日志，并与 Logstash 和 Kibana 等工具组成完整的可观测性技术栈，即 Elastic（ELK）Stack。

APISIX 支持通过 elasticsearch-logger 插件将日志直接转发到 Elasticsearch。随后可以在 Kibana 中搜索、筛选和可视化这些日志，从中获取管理应用所需的信息。

本指南介绍如何启用 elasticsearch-logger 插件，将 APISIX 与 ELK Stack 集成以实现可观测性。

前置条件

安装 Docker。
安装 cURL 以向服务发送验证请求。
按照快速入门教程在 Docker 中启动新的 APISIX 实例。

启动 Elasticsearch 和 Kibana

为本地示例使用的 Elasticsearch 内置用户设置密码：

export ELASTIC_PASSWORD="apisix-elastic-pass"
export KIBANA_SYSTEM_PASSWORD="apisix-kibana-pass"

创建数据卷，并在启用身份认证的情况下启动 Elasticsearch：

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

❶ 将 Elasticsearch 接入 APISIX 快速入门网络，使 APISIX 和 Kibana 可以通过容器名称访问它。

❷ 仅在这个隔离的本地示例中禁用 HTTP TLS。生产环境中请使用 HTTPS 端点，并保持插件的 ssl_verify 选项启用，以便 APISIX 验证 Elasticsearch 证书。

❸ 将 Elasticsearch 数据持久化到上面创建的命名 Docker 卷中。

等待 Elasticsearch 启动（最多两分钟），然后验证身份认证是否成功：

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"

设置 Kibana 连接 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

创建数据卷，并启动匹配版本的 Kibana：

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

启用 `elasticsearch-logger` 插件

全局启用 elasticsearch-logger，并创建用于生成日志的示例路由。你也可以仅在某个路由上启用该插件。

Admin API
ADC

在所有路由上启用 elasticsearch-logger 插件：

curl "http://127.0.0.1:9180/apisix/admin/global_rules/elasticsearch" -X PUT \
  -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

❶ 解析日期表达式，创建每日索引，例如 gateway-2026.07.21。

创建示例路由。将 pass_host 设为 node 会在 Host 请求头中发送上游主机名：

curl "http://127.0.0.1:9180/apisix/admin/routes/observability-logs" -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "/get",
    "upstream": {
      "type": "roundrobin",
      "pass_host": "node",
      "nodes": {
        "postman-echo.com:80": 1
      }
    }
  }'

adc-elasticsearch.yaml
global_rules:
  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
services:
  - name: postman-echo
    routes:
      - name: observability-logs
        uris:
          - /get
    upstream:
      type: roundrobin
      pass_host: node
      nodes:
        - host: postman-echo.com
          port: 80
          weight: 1

❶ 解析日期表达式，创建每日索引，例如 gateway-2026.07.21。

将配置同步到 APISIX：

adc sync -f adc-elasticsearch.yaml

自定义日志格式

生成流量之前，自定义 elasticsearch-logger 的日志格式。大多数 APISIX 日志插件都可以在插件本地（例如绑定到某个路由）和/或通过插件元数据在全局自定义日志格式。

使用内置变量将主机地址、时间戳和客户端 IP 地址添加到日志：

Admin API
ADC

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/elasticsearch-logger" -X PUT \
  -H "Content-Type: application/json" \
  --data-binary @- <<'EOF'
{
  "log_format": {
    "host": "$host",
    "timestamp": "$time_iso8601",
    "client_ip": "$remote_addr"
  }
}
EOF

adc-plugin-metadata.yaml
plugin_metadata:
  elasticsearch-logger:
    log_format:
      host: $host
      timestamp: $time_iso8601
      client_ip: $remote_addr

将配置同步到 APISIX：

adc sync -f adc-plugin-metadata.yaml -f adc-elasticsearch.yaml

配置 Kibana

发送十个请求，然后等待非活跃缓冲区刷新到 Elasticsearch：

for i in {1..10}; do
  curl -sS "http://127.0.0.1:9080/get" > /dev/null
done

sleep 6

列出基于日期的索引：

curl -u "elastic:${ELASTIC_PASSWORD}" \
  "http://127.0.0.1:9200/_cat/indices/gateway-*?v"

你应该看到包含文档的 gateway-YYYY.MM.DD 索引。检查其中一个已索引文档：

curl -u "elastic:${ELASTIC_PASSWORD}" \
  "http://127.0.0.1:9200/gateway-*/_search?pretty&size=1"

文档的 _source 应包含 host、timestamp 和 client_ip 字段。

在 Kibana 中查看日志

打开 Kibana，使用 elastic 用户和保存在 ELASTIC_PASSWORD 中的密码登录。

前往 Stack Management > Data Views，选择 Create data view，并配置以下值：

Name：APISIX logs
Index pattern：gateway-*
Timestamp field：timestamp

选择 Save data view to Kibana，然后前往 Discover 并选择 APISIX logs 数据视图。现在可以搜索和筛选已索引的网关请求。

Kibana Discover 中显示来自 Elasticsearch 的 APISIX 日志文档

下一步

参阅 elasticsearch-logger 插件参考，了解更多插件配置选项。

前置条件​

启动 Elasticsearch 和 Kibana​

启用 elasticsearch-logger 插件​

自定义日志格式​

配置 Kibana​

在 Kibana 中查看日志​

下一步​