elasticsearch-logger

描述

elasticsearch-logger 插件用于将 Apache APISIX 的请求日志转发到 Elasticsearch 中进行分析和存储。

启用该插件后 APISIX 将在 Log Phase 获取请求上下文信息并序列化为 Bulk 格式 后提交到批处理队列中，当触发批处理队列每批次最大处理容量或刷新缓冲区的最大时间时会将队列中的数据提交到 Elaticsearch 中。更多信息，请参考 Batch-Processor。

属性

名称类型必选项默认值描述
endpoint_addrstring废弃Elasticsearch API 推荐使用 endpoint_addrs
endpoint_addrsarray是Elasticsearch API。如果配置多个 endpoints，日志将会随机写入到各个 endpoints
fieldarray是Elasticsearch field配置信息。
field.indexstring是Elasticsearch _index field
field.typestring否Elasticsearch 默认值Elasticsearch _type field
log_formatobject否以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 $ 开头，则表明是要获取 APISIX 变量 或 NGINX 内置变量。
autharray否Elasticsearch authentication 配置信息
auth.usernamestring是Elasticsearch authentication 用户名。
auth.passwordstring是Elasticsearch authentication 密码。
ssl_verifyboolean否true当设置为 true 时则启用 SSL 验证。更多信息请参考 lua-nginx-module。
timeoutinteger否10发送给 Elasticsearch 请求超时时间。
include_req_bodyboolean否false当设置为 true 时，包含请求体。注意：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。
include_req_body_exprarray否当 include_req_body 属性设置为 true 时的过滤器。只有当此处设置的表达式求值为 true 时，才会记录请求体。有关更多信息，请参阅 lua-resty-expr 。
include_resp_bodyboolean否false当设置为 true 时，包含响应体。
include_resp_body_exprarray否当 include_resp_body 属性设置为 true 时进行过滤响应体，并且只有当此处设置的表达式计算结果为 true 时，才会记录响应体。更多信息，请参考 lua-resty-expr。

注意：schema 中还定义了 encrypt_fields = {"auth.password"}，这意味着该字段将会被加密存储在 etcd 中。具体参考 加密存储字段。

本插件支持使用批处理器来聚合并批量处理条目（日志和数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 5 秒钟或队列中的数据达到 1000 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 Batch-Processor 配置部分。

默认日志格式示例

  1. {
  2.     "upstream_latency": 2,
  3.     "apisix_latency": 100.9999256134,
  4.     "request": {
  5.         "size": 59,
  6.         "url": "http://localhost:1984/hello",
  7.         "method": "GET",
  8.         "querystring": {},
  9.         "headers": {
  10.             "host": "localhost",
  11.             "connection": "close"
  12.         },
  13.         "uri": "/hello"
  14.     },
  15.     "server": {
  16.         "version": "3.7.0",
  17.         "hostname": "localhost"
  18.     },
  19.     "client_ip": "127.0.0.1",
  20.     "upstream": "127.0.0.1:1980",
  21.     "response": {
  22.         "status": 200,
  23.         "headers": {
  24.             "content-length": "12",
  25.             "connection": "close",
  26.             "content-type": "text/plain",
  27.             "server": "APISIX/3.7.0"
  28.         },
  29.         "size": 118
  30.     },
  31.     "start_time": 1704524807607,
  32.     "route_id": "1",
  33.     "service_id": "",
  34.     "latency": 102.9999256134
  35. }

启用插件

你可以通过如下命令在指定路由上启用 elasticsearch-logger 插件：

完整配置示例

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "plugins":{
  5.         "elasticsearch-logger":{
  6.             "endpoint_addr":"http://127.0.0.1:9200",
  7.             "field":{
  8.                 "index":"services",
  9.                 "type":"collector"
  10.             },
  11.             "auth":{
  12.                 "username":"elastic",
  13.                 "password":"123456"
  14.             },
  15.             "ssl_verify":false,
  16.             "timeout": 60,
  17.             "retry_delay":1,
  18.             "buffer_duration":60,
  19.             "max_retry_count":0,
  20.             "batch_max_size":1000,
  21.             "inactive_timeout":5,
  22.             "name":"elasticsearch-logger"
  23.         }
  24.     },
  25.     "upstream":{
  26.         "type":"roundrobin",
  27.         "nodes":{
  28.             "127.0.0.1:1980":1
  29.         }
  30.     },
  31.     "uri":"/elasticsearch.do"
  32. }'

最小化配置示例

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "plugins":{
  5.         "elasticsearch-logger":{
  6.             "endpoint_addr":"http://127.0.0.1:9200",
  7.             "field":{
  8.                 "index":"services"
  9.             }
  10.         }
  11.     },
  12.     "upstream":{
  13.         "type":"roundrobin",
  14.         "nodes":{
  15.             "127.0.0.1:1980":1
  16.         }
  17.     },
  18.     "uri":"/elasticsearch.do"
  19. }'

测试插件

向配置 elasticsearch-logger 插件的路由发送请求

  1. curl -i http://127.0.0.1:9080/elasticsearch.do\?q\=hello
  2. HTTP/1.1 200 OK
  3. ...
  4. hello, world

现在，你可以从 Elasticsearch 获取相关日志。

  1. curl -X GET "http://127.0.0.1:9200/services/_search" | jq .
  2. {
  3.   "took": 0,
  4.    ...
  5.     "hits": [
  6.       {
  7.         "_index": "services",
  8.         "_type": "_doc",
  9.         "_id": "M1qAxYIBRmRqWkmH4Wya",
  10.         "_score": 1,
  11.         "_source": {
  12.           "apisix_latency": 0,
  13.           "route_id": "1",
  14.           "server": {
  15.             "version": "2.15.0",
  16.             "hostname": "apisix"
  17.           },
  18.           "request": {
  19.             "size": 102,
  20.             "uri": "/elasticsearch.do?q=hello",
  21.             "querystring": {
  22.               "q": "hello"
  23.             },
  24.             "headers": {
  25.               "user-agent": "curl/7.29.0",
  26.               "host": "127.0.0.1:9080",
  27.               "accept": "*/*"
  28.             },
  29.             "url": "http://127.0.0.1:9080/elasticsearch.do?q=hello",
  30.             "method": "GET"
  31.           },
  32.           "service_id": "",
  33.           "latency": 0,
  34.           "upstream": "127.0.0.1:1980",
  35.           "upstream_latency": 1,
  36.           "client_ip": "127.0.0.1",
  37.           "start_time": 1661170929107,
  38.           "response": {
  39.             "size": 192,
  40.             "headers": {
  41.               "date": "Mon, 22 Aug 2022 12:22:09 GMT",
  42.               "server": "APISIX/2.15.0",
  43.               "content-type": "text/plain; charset=utf-8",
  44.               "connection": "close",
  45.               "transfer-encoding": "chunked"
  46.             },
  47.             "status": 200
  48.           }
  49.         }
  50.       }
  51.     ]
  52.   }
  53. }

插件元数据设置

名称类型必选项默认值有效值描述
log_formatobject可选以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 $ 开头，则表明是要获取 APISIX 变量 或 Nginx 内置变量。请注意，该设置是全局生效的，因此在指定 log_format 后，将对所有绑定 elasticsearch-logger 的 Route 或 Service 生效。

设置日志格式示例

  1. curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/elasticsearch-logger \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "log_format": {
  5.         "host": "$host",
  6.         "@timestamp": "$time_iso8601",
  7.         "client_ip": "$remote_addr"
  8.     }
  9. }'

在日志收集处，将得到类似下面的日志：

  1. {"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}
  2. {"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}

向配置 elasticsearch-logger 插件的路由发送请求

  1. curl -i http://127.0.0.1:9080/elasticsearch.do\?q\=hello
  2. HTTP/1.1 200 OK
  3. ...
  4. hello, world

现在，你可以从 Elasticsearch 获取相关日志。

  1. curl -X GET "http://127.0.0.1:9200/services/_search" | jq .
  2. {
  3.   "took": 0,
  4.   ...
  5.   "hits": {
  6.     "total": {
  7.       "value": 1,
  8.       "relation": "eq"
  9.     },
  10.     "max_score": 1,
  11.     "hits": [
  12.       {
  13.         "_index": "services",
  14.         "_type": "_doc",
  15.         "_id": "NVqExYIBRmRqWkmH4WwG",
  16.         "_score": 1,
  17.         "_source": {
  18.           "@timestamp": "2022-08-22T20:26:31+08:00",
  19.           "client_ip": "127.0.0.1",
  20.           "host": "127.0.0.1",
  21.           "route_id": "1"
  22.         }
  23.       }
  24.     ]
  25.   }
  26. }

删除插件元数据

  1. curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/elasticsearch-logger \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X DELETE

删除插件

当你需要删除该插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4.     "plugins":{},
  5.     "upstream":{
  6.         "type":"roundrobin",
  7.         "nodes":{
  8.             "127.0.0.1:1980":1
  9.         }
  10.     },
  11.     "uri":"/elasticsearch.do"
  12. }'