This is an automated email from the ASF dual-hosted git repository.
Baoyuantop pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 2a75cedcf docs: update loki-logger and elasticsearch-logger plugin
docs (#13271)
2a75cedcf is described below
commit 2a75cedcf9e7cd4927c2e59cdb6b780d5144e383
Author: Yilia Lin <[email protected]>
AuthorDate: Tue Apr 28 15:18:42 2026 +0800
docs: update loki-logger and elasticsearch-logger plugin docs (#13271)
---
docs/en/latest/plugins/elasticsearch-logger.md | 106 +++++++++++++++----
docs/en/latest/plugins/loki-logger.md | 12 +--
docs/zh/latest/plugins/elasticsearch-logger.md | 134 ++++++++++++++++++-------
docs/zh/latest/plugins/loki-logger.md | 52 +++++-----
4 files changed, 216 insertions(+), 88 deletions(-)
diff --git a/docs/en/latest/plugins/elasticsearch-logger.md
b/docs/en/latest/plugins/elasticsearch-logger.md
index d555cd122..dac354150 100644
--- a/docs/en/latest/plugins/elasticsearch-logger.md
+++ b/docs/en/latest/plugins/elasticsearch-logger.md
@@ -37,24 +37,24 @@ The `elasticsearch-logger` Plugin pushes request and
response logs in batches to
## Attributes
-| Name | Type | Required | Default |
Description |
-| ------------- | ------- | -------- | --------------------------- |
------------------------------------------------------------ |
-| endpoint_addrs | array[string] | True | |
Elasticsearch API endpoint addresses. If multiple endpoints are configured,
they will be written randomly. |
-| field | object | True | |
Elasticsearch `field` configuration. |
-| field.index | string | True | |
Elasticsearch [_index
field](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-index-field.html#mapping-index-field).
|
-| log_format | object | False | | Custom log
format as key-value pairs in JSON. Values support strings and nested objects
(up to five levels deep; deeper fields are truncated). Within strings,
[APISIX](../apisix-variable.md) or [NGINX
variables](http://nginx.org/en/docs/varindex.html) can be referenced by
prefixing with `$`. |
-| auth | array | False | |
Elasticsearch
[authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
configuration. |
-| auth.username | string | True | |
Elasticsearch
[authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
username. |
-| auth.password | string | True | |
Elasticsearch
[authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
password. |
-| headers | object | False | | Custom headers
to send with requests as key-value pairs. For example: `{"Authorization":
"Bearer token", "X-API-Key": "key"}`. |
-| ssl_verify | boolean | False | true | If true,
perform SSL verification. |
-| timeout | integer | False | 10 |
Elasticsearch send data timeout in seconds. |
-| include_req_body | boolean | False | 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] | False | | An array of
one or more conditions in the form of
[lua-resty-expr](https://github.com/api7/lua-resty-expr). Used when the
`include_req_body` is true. Request body would only be logged when the
expressions configured here evaluate to true. |
-| max_req_body_bytes | integer | False | 524288 | Request bodies within this
size will be logged, if the size exceeds the configured value it will be
truncated before logging. |
-| include_resp_body | boolean | False | false | If true,
include the response body in the log. |
-| include_resp_body_expr | array[array] | False | | An array of
one or more conditions in the form of
[lua-resty-expr](https://github.com/api7/lua-resty-expr). Used when the
`include_resp_body` is true. Response body would only be logged when the
expressions configured here evaluate to true. |
-| max_resp_body_bytes | integer | False | 524288 | Response bodies within this
size will be logged, if the size exceeds the configured value it will be
truncated before logging. |
+| Name | Type | Required | Default | Valid
values | Description |
+| ------------- | ------- | -------- | --------------------------- |
------------ | ------------------------------------------------------------ |
+| endpoint_addrs | array[string] | True | |
| Elasticsearch API endpoint addresses. If multiple endpoints are
configured, they will be written randomly. |
+| field | object | True | |
| Elasticsearch field configuration. |
+| field.index | string | True | |
| Elasticsearch [_index
field](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-index-field.html#mapping-index-field).
Supports the configuration of a [lua time
format](https://www.lua.org/pil/22.1.html) in curly brackets to include the
current date, such as `service-{%Y-%m-%d}`. |
+| log_format | object | False | |
| Custom log format as key-value pairs in JSON. Values support strings and
nested objects (up to five levels deep; deeper fields are truncated). Within
strings, [APISIX](../apisix-variable.md) or [NGINX
variables](http://nginx.org/en/docs/varindex.html) can be referenced by
prefixing with `$`. |
+| auth | object | False | |
| Elasticsearch
[authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
configuration. |
+| auth.username | string | False | |
| Elasticsearch
[authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
username. Required if `auth` is configured. Must be provided together with
`auth.password`. |
+| auth.password | string | False | |
| Elasticsearch
[authentication](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
password. Required if `auth` is configured. Must be provided together with
`auth.username`. The secret is encrypted with AES before being stored in etcd. |
+| headers | object | False | | |
Custom HTTP request headers to include in requests sent to Elasticsearch, as
key-value pairs. Can be used as an alternative or complement to `auth` for
authentication and other purposes. Available in APISIX from 3.16.0. |
+| ssl_verify | boolean | False | true |
| If true, perform SSL verification. |
+| timeout | integer | False | 10 |
| Elasticsearch send data timeout in seconds. |
+| include_req_body | boolean | False | 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] | False | | |
An array of one or more conditions in the form of
[lua-resty-expr](https://github.com/api7/lua-resty-expr). Used when the
`include_req_body` is true. Request body would only be logged when the
expressions configured here evaluate to true. |
+| max_req_body_bytes | integer | False | 524288 | >=1 | Request
bodies within this size will be logged, if the size exceeds the configured
value it will be truncated before logging. |
+| include_resp_body | boolean | False | false | |
If true, include the response body in the log. |
+| include_resp_body_expr | array[array] | False | | |
An array of one or more conditions in the form of
[lua-resty-expr](https://github.com/api7/lua-resty-expr). Used when the
`include_resp_body` is true. Response body would only be logged when the
expressions configured here evaluate to true. |
+| max_resp_body_bytes | integer | False | 524288 | >=1 | Response
bodies within this size will be logged, if the size exceeds the configured
value it will be truncated before logging. |
NOTE: `encrypt_fields = {"auth.password"}` is also defined in the schema,
which means that the field will be stored encrypted in etcd. See [encrypted
storage fields](../plugin-develop.md#encrypted-storage-fields).
@@ -171,7 +171,7 @@ Navigate to the Kibana dashboard on
[localhost:5601](http://localhost:5601) and
"headers": {
"content-type": "application/json",
"access-control-allow-credentials": "true",
- "server": "APISIX/3.11.0",
+ "server": "APISIX/3.13.0",
"content-length": "390",
"access-control-allow-origin": "*",
"connection": "close",
@@ -187,7 +187,7 @@ Navigate to the Kibana dashboard on
[localhost:5601](http://localhost:5601) and
"upstream": "50.19.58.113:80",
"server": {
"hostname": "0b9a772e68f8",
- "version": "3.11.0"
+ "version": "3.13.0"
},
"service_id": "",
"client_ip": "192.168.65.1"
@@ -198,7 +198,7 @@ Navigate to the Kibana dashboard on
[localhost:5601](http://localhost:5601) and
}
```
-### Log Request and Response Headers With Plugin Metadata
+### Customize Log Format With Plugin Metadata
The following example demonstrates how you can customize log format using
[Plugin Metadata](../terminology/plugin-metadata.md) and [NGINX
variables](http://nginx.org/en/docs/varindex.html) to log specific headers from
request and response.
@@ -217,6 +217,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
"endpoint_addrs": ["http://elasticsearch:9200";],
"field": {
"index": "gateway"
+ }
}
},
"upstream": {
@@ -277,7 +278,7 @@ Navigate to the Kibana dashboard on
[localhost:5601](http://localhost:5601) and
The following example demonstrates how you can conditionally log request body.
-Create a Route with `elasticsearch-logger` to only log request body if the URL
query string `log_body` is `true`:
+Create a Route with `elasticsearch-logger` to only log request body if the URL
query string `log_body` is `yes`:
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
@@ -447,3 +448,64 @@ As a workaround, you may be able to use the NGINX variable
`$request_body` in th
```
:::
+
+### Include Request Date in Elasticsearch Index
+
+The following example demonstrates how you can configure the
`elasticsearch-logger` Plugin to include the request date in the Elasticsearch
index name.
+
+Create a Route with `elasticsearch-logger` as follows:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "elasticsearch-logger-route",
+ "uri": "/anything",
+ "plugins": {
+ "elasticsearch-logger": {
+ "endpoint_addrs": ["http://elasticsearch:9200";],
+ "field": {
+ "index": "apisix-{%Y.%m.%d}"
+ }
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "httpbin.org:80": 1
+ },
+ "type": "roundrobin"
+ }
+ }'
+```
+
+The `index` field uses a [lua time format](https://www.lua.org/pil/22.1.html)
in curly brackets to append the current year, month, and date to the index name.
+
+Send a request to the Route to generate a log entry:
+
+```shell
+curl -i "http://127.0.0.1:9080/anything";
+```
+
+You should receive an `HTTP/1.1 200 OK` response.
+
+Navigate to the Kibana dashboard on [localhost:5601](http://localhost:5601)
and under __Discover__ tab, create a new index pattern `apisix*` to fetch the
data from Elasticsearch. Once configured, navigate back to the __Discover__ tab
and you should see a log generated with an index name containing the current
date, similar to the following:
+
+```json
+{
+ "_index": "apisix-2025.01.13",
+ "_id": "CE-KL5QB0kdYRG7dEiTJ",
+ "_version": 1,
+ "_score": 1,
+ "_source": {
+ "request": {
+ ...
+ },
+ "response": {
+ ...
+ },
+ "route_id": "elasticsearch-logger-route",
+ "client_ip": "192.168.65.1"
+ },
+ ...
+}
+```
diff --git a/docs/en/latest/plugins/loki-logger.md
b/docs/en/latest/plugins/loki-logger.md
index 0f809ba0e..07d77f857 100644
--- a/docs/en/latest/plugins/loki-logger.md
+++ b/docs/en/latest/plugins/loki-logger.md
@@ -47,7 +47,7 @@ When enabled, the Plugin will serialize the request context
information to [JSON
| tenant_id | string | False | fake | | Loki tenant ID. According to Loki's
[multi-tenancy
documentation](https://grafana.com/docs/loki/latest/operations/multi-tenancy/#multi-tenancy),
the default value is set to `fake` under single-tenancy. |
| headers | object | False | | | Key-value pairs of request headers
(settings for `X-Scope-OrgID` and `Content-Type` will be ignored). |
| log_labels | object | False | {job = "apisix"} | | Loki log label. Support
[NGINX variables](https://nginx.org/en/docs/varindex.html) and constant strings
in values. Variables should be prefixed with a `$` sign. For example, the label
can be `{"origin" = "apisix"}` or `{"origin" = "$remote_addr"}`. |
-| ssl_verify | boolean | False | true | | If true, verify
Loki's SSL certificates. |
+| ssl_verify | boolean | False | false | | If true, verify
Loki's SSL certificates. |
| timeout | integer | False | 3000 | [1, 60000] | Timeout
for the Loki service HTTP call in milliseconds. |
| keepalive | boolean | False | true | | If true, keep the
connection alive for multiple requests. |
| keepalive_timeout | integer | False | 60000 | >=1000 | Keepalive
timeout in milliseconds. |
@@ -67,10 +67,10 @@ This Plugin supports using batch processors to aggregate
and process entries (lo
You can also configure log format on a global scale using the [Plugin
Metadata](../terminology/plugin-metadata.md), which configures the log format
for all `loki-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.
-| Name | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| log_format | object | False | | Custom log format as key-value pairs in
JSON. Values support strings and nested objects (up to five levels deep; deeper
fields are truncated). Within strings, [APISIX
variables](../apisix-variable.md) and [NGINX
variables](http://nginx.org/en/docs/varindex.html) can be referenced by
prefixing with `$`. |
-| max_pending_entries | integer | False | | Maximum number of pending entries
that can be buffered in batch processor before it starts dropping them. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| log_format | object | False | | | Custom log format as key-value pairs in
JSON. Values support strings and nested objects (up to five levels deep; deeper
fields are truncated). Within strings, [APISIX
variables](../apisix-variable.md) and [NGINX
variables](http://nginx.org/en/docs/varindex.html) can be referenced by
prefixing with `$`. |
+| max_pending_entries | integer | False | | | Maximum number of pending
entries that can be buffered in batch processor before it starts dropping them.
|
## Examples
@@ -370,7 +370,7 @@ As a workaround, you may be able to use the NGINX variable
`$request_body` in th
```json
{
- "kafka-logger": {
+ "loki-logger": {
...,
"log_format": {"body": "$request_body"}
}
diff --git a/docs/zh/latest/plugins/elasticsearch-logger.md
b/docs/zh/latest/plugins/elasticsearch-logger.md
index aad8a3ce8..01db48059 100644
--- a/docs/zh/latest/plugins/elasticsearch-logger.md
+++ b/docs/zh/latest/plugins/elasticsearch-logger.md
@@ -38,22 +38,24 @@ description: elasticsearch-logger Plugin 将请求和响应日志批量推送到
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 描述
|
-| ------------- | ------- | -------- | -------------------- |
------------------------------------------------------------ |
-| endup_addrs | array[string] | 是 | | Elasticsearch API 端点地址。如果配置了多个端点，则会随机写入。
|
-| field | object | 是 | | Elasticsearch `field` 配置。 |
-| field.index | string | 是 | | Elasticsearch [_index
字段](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-index-field.html#mapping-index-field)。
|
-| log_format | object | 否 | | 自定义日志格式以 JSON
的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过 `$` 前缀引用
[APISIX](../apisix-variable.md) 或 [NGINX
变量](http://nginx.org/en/docs/varindex.html)。 |
-| auth | array | 否 | | Elasticsearch
[身份验证](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
配置。 |
-| auth.username | string | 是 | | Elasticsearch
[身份验证](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
用户名。 |
-| auth.password | string | 是 | | Elasticsearch
[身份验证](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
密码。 |
-| headers | object | 否 | | 自定义请求标头，以键值对形式配置。例如 `{"Authorization": "Bearer
token", "X-API-Key": "key"}`。 |
-| ssl_verify | boolean | 否 | true | 如果为 true，则执行 SSL 验证。 |
-| timeout | integer | 否 | 10 | Elasticsearch 发送数据超时（秒）。 |
-| include_req_body | boolean | 否 | false |如果为
true，则将请求主体包含在日志中。请注意，如果请求主体太大而无法保存在内存中，则由于 NGINX 的限制而无法记录。|
-| include_req_body_expr | array[array] | 否 | | 一个或多个条件的数组，形式为
[lua-resty-expr](https://github.com/api7/lua-resty-expr)。在 `include_req_body` 为
true 时使用。仅当此处配置的表达式计算结果为 true 时，才会记录请求主体。|
-| include_resp_body | boolean | 否 | false | 如果为 true，则将响应主体包含在日志中。|
-| include_resp_body_expr | array[array] | 否 | | 一个或多个条件的数组，形式为
[lua-resty-expr](https://github.com/api7/lua-resty-expr)。在 `include_resp_body`
为 true 时使用。仅当此处配置的表达式计算结果为 true 时，才会记录响应主体。|
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ------------- | ------- | -------- | -------------------- | ------------ |
------------------------------------------------------------ |
+| endpoint_addrs | array[string] | 是 | | | Elasticsearch API
端点地址。如果配置了多个端点，则会随机写入。 |
+| field | object | 是 | | | Elasticsearch 字段配置。 |
+| field.index | string | 是 | | | Elasticsearch [_index
字段](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-index-field.html#mapping-index-field)。支持在花括号中使用
[lua 时间格式](https://www.lua.org/pil/22.1.html) 来包含当前日期，例如 `service-{%Y-%m-%d}`。
|
+| log_format | object | 否 | | | 自定义日志格式以 JSON
的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过 `$` 前缀引用
[APISIX](../apisix-variable.md) 或 [NGINX
变量](http://nginx.org/en/docs/varindex.html)。 |
+| auth | object | 否 | | | Elasticsearch
[身份验证](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
配置。 |
+| auth.username | string | 否 | | | Elasticsearch
[身份验证](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
用户名。当配置 `auth` 时必填，需与 `auth.password` 成对配置。 |
+| auth.password | string | 否 | | | Elasticsearch
[身份验证](https://www.elastic.co/guide/en/elasticsearch/reference/current/setting-up-authentication.html)
密码。当配置 `auth` 时必填，需与 `auth.username` 成对配置。该密钥在存储到 etcd 之前会使用 AES 加密。 |
+| headers | object | 否 | | | 自定义 HTTP 请求标头，以键值对形式包含在发送给
Elasticsearch 的请求中。可作为 `auth` 的替代或补充，用于身份验证和其他目的。在 APISIX 3.16.0 中可用。 |
+| ssl_verify | boolean | 否 | true | | 如果为 true，则执行 SSL 验证。 |
+| timeout | integer | 否 | 10 | | Elasticsearch 发送数据超时（秒）。 |
+| include_req_body | boolean | 否 | false | | 如果为
true，则将请求主体包含在日志中。请注意，如果请求主体太大而无法保存在内存中，则由于 NGINX 的限制而无法记录。 |
+| include_req_body_expr | array[array] | 否 | | | 一个或多个条件的数组，形式为
[lua-resty-expr](https://github.com/api7/lua-resty-expr)。在 `include_req_body` 为
true 时使用。仅当此处配置的表达式计算结果为 true 时，才会记录请求主体。 |
+| max_req_body_bytes | integer | 否 | 524288 | >=1 |
记录请求主体的最大字节数。如果请求主体超过此值，则会在记录前截断。在 APISIX 3.16.0 中可用。 |
+| include_resp_body | boolean | 否 | false | | 如果为
true，则将响应主体包含在日志中。 |
+| include_resp_body_expr | array[array] | 否 | | | 一个或多个条件的数组，形式为
[lua-resty-expr](https://github.com/api7/lua-resty-expr)。在 `include_resp_body`
为 true 时使用。仅当此处配置的表达式计算结果为 true 时，才会记录响应主体。 |
+| max_resp_body_bytes | integer | 否 | 524288 | >=1 |
记录响应主体的最大字节数。如果响应主体超过此值，则会在记录前截断。在 APISIX 3.16.0 中可用。 |
注意：schema 中还定义了 `encrypt_fields = {"auth.password"}`，这意味着该字段将会被加密存储在 etcd
中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
@@ -61,10 +63,10 @@ description: elasticsearch-logger Plugin 将请求和响应日志批量推送到
## Plugin Metadata
-| Name | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
+| 名称 | 类型 | 必选项 | 默认值 | 描述 |
+|------|------|--------|--------|------|
| log_format | object | 否 | | 自定义日志格式以 JSON
的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过 `$` 前缀引用 [APISIX
变量](../apisix-variable.md) 和 [NGINX
变量](http://nginx.org/en/docs/varindex.html)。 |
-| max_pending_entries | integer | 否 | | | 在批处理器中开始删除待处理条目之前可以购买的最大待处理条目数。|
+| max_pending_entries | integer | 否 | | 在批处理器开始丢弃条目之前，可缓冲在批处理器中的最大待处理条目数。 |
## 示例
@@ -96,11 +98,11 @@ docker run -d \
docker.elastic.co/kibana/kibana:7.17.1
```
-如果成功，您应该在 [localhost:5601](http://localhost:5601) 上看到 Kibana 仪表板。
+如果成功，你应该在 [localhost:5601](http://localhost:5601) 上看到 Kibana 仪表板。
:::note
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
@@ -143,9 +145,9 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl -i "http://127.0.0.1:9080/anything";
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+你应该会收到 `HTTP/1.1 200 OK` 响应。
-导航到 [localhost:5601](http://localhost:5601) 上的 Kibana 仪表板，并在 __Discover__
选项卡下创建一个新的索引模式 `gateway` 以从 Elasticsearch 获取数据。配置完成后，导航回 __Discover__
选项卡，您应该会看到生成的日志，类似于以下内容：
+导航到 [localhost:5601](http://localhost:5601) 上的 Kibana 仪表板，并在 __Discover__
选项卡下创建一个新的索引模式 `gateway` 以从 Elasticsearch 获取数据。配置完成后，导航回 __Discover__
选项卡，你应该会看到生成的日志，类似于以下内容：
```json
{
@@ -170,7 +172,7 @@ curl -i "http://127.0.0.1:9080/anything";
"headers": {
"content-type": "application/json",
"access-control-allow-credentials": "true",
- "server": "APISIX/3.11.0",
+ "server": "APISIX/3.13.0",
"content-length": "390",
"access-control-allow-origin": "*",
"connection": "close",
@@ -197,7 +199,7 @@ curl -i "http://127.0.0.1:9080/anything";
}
```
-### 使用 Plugin Metadata 记录请求和响应标头
+### 使用 Plugin Metadata 自定义日志格式
以下示例演示了如何使用 [Plugin Metadata](../terminology/plugin-metadata.md) 和 [NGINX
变量](http://nginx.org/en/docs/varindex.html) 自定义日志格式，以记录请求和响应中的特定标头。
@@ -216,6 +218,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
"endpoint_addrs": ["http://elasticsearch:9200";],
"field": {
"index": "gateway"
+ }
}
},
"upstream": {
@@ -249,9 +252,9 @@ curl
"http://127.0.0.1:9180/apisix/admin/plugin_metadata/elasticsearch-logger"; -
curl -i "http://127.0.0.1:9080/anything"; -H "env: dev"
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+你应该会收到 `HTTP/1.1 200 OK` 响应。
-导航到 [localhost:5601](http://localhost:5601) 上的 Kibana 仪表板，并在 __Discover__
选项卡下创建一个新的索引模式 `gateway` 以从 Elasticsearch 获取数据（如果您尚未这样做）。配置完成后，导航回 __Discover__
选项卡，您应该会看到生成的日志，类似于以下内容：
+导航到 [localhost:5601](http://localhost:5601) 上的 Kibana 仪表板，并在 __Discover__
选项卡下创建一个新的索引模式 `gateway` 以从 Elasticsearch 获取数据（如果你尚未这样做）。配置完成后，导航回 __Discover__
选项卡，你应该会看到生成的日志，类似于以下内容：
```json
{
@@ -276,7 +279,7 @@ curl -i "http://127.0.0.1:9080/anything"; -H "env: dev"
以下示例演示了如何有条件地记录请求主体。
-使用 `elasticsearch-logger` 创建路由，仅在 URL 查询字符串 `log_body` 为 `true` 时记录请求主体：
+使用 `elasticsearch-logger` 创建路由，仅在 URL 查询字符串 `log_body` 为 `yes` 时记录请求主体：
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
@@ -309,9 +312,9 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl -i "http://127.0.0.1:9080/anything?log_body=yes"; -X POST -d '{"env":
"dev"}'
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+你应该会收到 `HTTP/1.1 200 OK` 响应。
-导航到 [localhost:5601](http://localhost:5601) 上的 Kibana 仪表板，并在 __Discover__
选项卡下创建一个新的索引模式 `gateway` 以从 Elasticsearch 获取数据（如果您尚未这样做）。配置完成后，导航回 __Discover__
选项卡，您应该会看到生成的日志，类似于以下内容：
+导航到 [localhost:5601](http://localhost:5601) 上的 Kibana 仪表板，并在 __Discover__
选项卡下创建一个新的索引模式 `gateway` 以从 Elasticsearch 获取数据（如果你尚未这样做）。配置完成后，导航回 __Discover__
选项卡，你应该会看到生成的日志，类似于以下内容：
```json
{
@@ -341,7 +344,7 @@ curl -i "http://127.0.0.1:9080/anything?log_body=yes"; -X
POST -d '{"env": "dev"}
"response": {
"headers": {
"content-type": "application/json",
- "server": "APISIX/3.11.0",
+ "server": "APISIX/3.13.0",
"access-control-allow-credentials": "true",
"content-length": "548",
"access-control-allow-origin": "*",
@@ -375,7 +378,7 @@ curl -i "http://127.0.0.1:9080/anything?log_body=yes"; -X
POST -d '{"env": "dev"}
curl -i "http://127.0.0.1:9080/anything"; -X POST -d '{"env": "dev"}'
```
-导航到 Kibana 仪表板 __Discover__ 选项卡，您应该看到生成的日志，但没有请求正文：
+导航到 Kibana 仪表板 __Discover__ 选项卡，你应该看到生成的日志，但没有请求正文：
```json
{
@@ -403,7 +406,7 @@ curl -i "http://127.0.0.1:9080/anything"; -X POST -d
'{"env": "dev"}'
"headers": {
"content-type": "application/json",
"access-control-allow-credentials": "true",
- "server": "APISIX/3.11.0",
+ "server": "APISIX/3.13.0",
"content-length": "510",
"access-control-allow-origin": "*",
"connection": "close",
@@ -432,9 +435,9 @@ curl -i "http://127.0.0.1:9080/anything"; -X POST -d
'{"env": "dev"}'
:::info
-如果您除了将 `include_req_body` 或 `include_resp_body` 设置为 `true` 之外还自定义了
`log_format`，则插件不会在日志中包含正文。
+如果你除了将 `include_req_body` 或 `include_resp_body` 设置为 `true` 之外还自定义了
`log_format`，则插件不会在日志中包含正文。
-作为一种解决方法，您可以在日志格式中使用 NGINX 变量 `$request_body`，例如：
+作为一种解决方法，你可以在日志格式中使用 NGINX 变量 `$request_body`，例如：
```json
{
@@ -446,3 +449,64 @@ curl -i "http://127.0.0.1:9080/anything"; -X POST -d
'{"env": "dev"}'
```
:::
+
+### 在 Elasticsearch 索引中包含请求日期
+
+以下示例演示了如何配置 `elasticsearch-logger` 插件，以在 Elasticsearch 索引名称中包含请求日期。
+
+使用 `elasticsearch-logger` 创建路由，如下所示：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "elasticsearch-logger-route",
+ "uri": "/anything",
+ "plugins": {
+ "elasticsearch-logger": {
+ "endpoint_addrs": ["http://elasticsearch:9200";],
+ "field": {
+ "index": "apisix-{%Y.%m.%d}"
+ }
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "httpbin.org:80": 1
+ },
+ "type": "roundrobin"
+ }
+ }'
+```
+
+`index` 字段在花括号中使用 [lua
时间格式](https://www.lua.org/pil/22.1.html)，将当前年、月、日附加到索引名称中。
+
+向路由发送请求以生成日志条目：
+
+```shell
+curl -i "http://127.0.0.1:9080/anything";
+```
+
+你应该会收到 `HTTP/1.1 200 OK` 响应。
+
+导航到 [localhost:5601](http://localhost:5601) 上的 Kibana 仪表板，并在 __Discover__
选项卡下创建一个新的索引模式 `apisix*` 以从 Elasticsearch 获取数据。配置完成后，导航回 __Discover__
选项卡，你应该会看到生成的日志，索引名称中包含当前日期，类似于以下内容：
+
+```json
+{
+ "_index": "apisix-2025.01.13",
+ "_id": "CE-KL5QB0kdYRG7dEiTJ",
+ "_version": 1,
+ "_score": 1,
+ "_source": {
+ "request": {
+ ...
+ },
+ "response": {
+ ...
+ },
+ "route_id": "elasticsearch-logger-route",
+ "client_ip": "192.168.65.1"
+ },
+ ...
+}
+```
diff --git a/docs/zh/latest/plugins/loki-logger.md
b/docs/zh/latest/plugins/loki-logger.md
index 3cff50870..a0ff70592 100644
--- a/docs/zh/latest/plugins/loki-logger.md
+++ b/docs/zh/latest/plugins/loki-logger.md
@@ -41,13 +41,13 @@ description: loki-logger 插件通过 Loki HTTP API
/loki/api/v1/push 将请求
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-|--|---|---|---|---|
-| end_addrs | array[string] | 是 | | | Loki API URL，例如
`http://127.0.0.1:3100`。如果配置了多个端点，日志将被推送到列表中随机确定的端点。 |
-| end_uri | string | 否 | /loki/api/v1/push | | Loki 提取端点的 URI 路径。 |
+|--|---|---|---|---|---|
+| endpoint_addrs | array[string] | 是 | | | Loki API URL，例如
`http://127.0.0.1:3100`。如果配置了多个端点，日志将被推送到列表中随机确定的端点。 |
+| endpoint_uri | string | 否 | /loki/api/v1/push | | Loki 提取端点的 URI 路径。 |
| tenant_id | string | 否 | fake | | Loki 租户 ID。根据 Loki 的
[多租户文档](https://grafana.com/docs/loki/latest/operations/multi-tenancy/#multi-tenancy)，在单租户下默认值设置为
`fake`。 |
| headers | object | 否 | | | 请求头键值对（对 `X-Scope-OrgID` 和 `Content-Type`
的设置将会被忽略）。 |
| log_labels | object | 否 | {job = "apisix"} | | Loki 日志标签。支持 [NGINX
变量](https://nginx.org/en/docs/varindex.html) 和值中的常量字符串。变量应以 `$` 符号为前缀。例如，标签可以是
`{"origin" = "apisix"}` 或 `{"origin" = "$remote_addr"}`。|
-| ssl_verify | boolean | 否 | true | | 如果为 true，则验证 Loki 的 SSL 证书。|
+| ssl_verify | boolean | 否 | false | | 如果为 true，则验证 Loki 的 SSL 证书。|
| timeout | integer | 否 | 3000 | [1, 60000] | Loki 服务 HTTP 调用的超时时间（以毫秒为单位）。|
| keepalive | boolean | 否 | true | | 如果为 true，则保持连接以应对多个请求。|
| keepalive_timeout | integer | 否 | 60000 | >=1000 | Keepalive 超时时间（以毫秒为单位）。|
@@ -56,19 +56,21 @@ description: loki-logger 插件通过 Loki HTTP API
/loki/api/v1/push 将请求
| name | string | 否 | loki-logger | | 批处理器插件的唯一标识符。如果使用
[Prometheus](./prometheus.md) 监控 APISIX 指标，则名称会导出到
`apisix_batch_process_entries`。 |
| include_req_body | boolean | 否 | false | | 如果为
true，则将请求正文包含在日志中。请注意，如果请求正文太大而无法保存在内存中，则由于 NGINX 的限制而无法记录。 |
| include_req_body_expr | array[array] | 否 | | |一个或多个
[lua-resty-expr](https://github.com/api7/lua-resty-expr) 形式条件的数组。在
`include_req_body` 为 true 时使用。仅当此处配置的表达式计算结果为 true 时，才会记录请求正文。|
+| max_req_body_bytes | integer | 否 | 524288 | >=1 |
记录请求正文的最大字节数。如果请求正文超过此值，则会在记录前截断。|
| include_resp_body | boolean | 否 | false | | 如果为 true，则将响应正文包含在日志中。|
| include_resp_body_expr | array[array] | 否 | | | 一个或多个
[lua-resty-expr](https://github.com/api7/lua-resty-expr) 形式条件的数组。在
`include_resp_body` 为 true 时使用。仅当此处配置的表达式计算结果为 true 时，才会记录响应正文。|
+| max_resp_body_bytes | integer | 否 | 524288 | >=1 |
记录响应正文的最大字节数。如果响应正文超过此值，则会在记录前截断。|
该插件支持使用批处理器对条目（日志/数据）进行批量聚合和处理，避免了频繁提交数据的需求。批处理器每隔 `5` 秒或当队列中的数据达到 `1000`
时提交数据。有关更多信息或设置自定义配置，请参阅 [批处理器](../batch-processor.md#configuration)。
## Plugin Metadata
-您还可以使用 [Plugin Metadata](../terminology/plugin-metadata.md) 全局配置日志格式，该 Plugin
Metadata 配置所有 `loki-logger` 插件实例的日志格式。如果在单个插件实例上配置的日志格式与在 Plugin Metadata
上配置的日志格式不同，则在单个插件实例上配置的日志格式优先。
+你还可以使用 [Plugin Metadata](../terminology/plugin-metadata.md) 全局配置日志格式，该 Plugin
Metadata 配置所有 `loki-logger` 插件实例的日志格式。如果在单个插件实例上配置的日志格式与在 Plugin Metadata
上配置的日志格式不同，则在单个插件实例上配置的日志格式优先。
-| 名称 | 类型 | 必选项 | 默认值 | 描述 |
-|------|------|----------|--|-------------|
-| log_format | object | 否 | | 日志格式以 JSON
的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX
变量](../apisix-variable.md) 和 [NGINX
变量](http://nginx.org/en/docs/varindex.html)。 |
-| max_pending_entries | integer | 否 | | | 在批处理器中开始删除待处理条目之前可以购买的最大待处理条目数。|
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| log_format | object | 否 | | | 日志格式以 JSON
的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX
变量](../apisix-variable.md) 和 [NGINX
变量](http://nginx.org/en/docs/varindex.html)。 |
+| max_pending_entries | integer | 否 | | | 在批处理器开始丢弃条目之前，可缓冲在批处理器中的最大待处理条目数。 |
## 示例
@@ -89,11 +91,11 @@ docker run -d --name=apisix-quickstart-grafana \
grafana/grafana-oss
```
-要连接 Loki 和 Grafana，请访问 Grafana，网址为
[`http://localhost:3000`](http://localhost:3000)。在 __Connections > Data
sources__ 下，添加新数据源并选择 Loki。您的连接 URL 应遵循 `http://{your_ip_address}:3100`
的格式。保存新数据源时，Grafana 还应测试连接，您应该会看到 Grafana 通知数据源已成功连接。
+要连接 Loki 和 Grafana，请访问 Grafana，网址为
[`http://localhost:3000`](http://localhost:3000)。在 __Connections > Data
sources__ 下，添加新数据源并选择 Loki。你的连接 URL 应遵循 `http://{your_ip_address}:3100`
的格式。保存新数据源时，Grafana 还应测试连接，你应该会看到 Grafana 通知数据源已成功连接。
:::note
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+你可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed
's/"//g')
@@ -133,9 +135,9 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9080/anything";
```
-您应该会收到所有请求的“HTTP/1.1 200 OK”响应。
+你应该会收到所有请求的“HTTP/1.1 200 OK”响应。
-导航到 [Grafana explore view](http://localhost:3000/explore) 并运行查询 `job =
apisix`。您应该会看到与您的请求相对应的许多日志，例如以下内容：
+导航到 [Grafana explore view](http://localhost:3000/explore) 并运行查询 `job =
apisix`。你应该会看到与你的请求相对应的许多日志，例如以下内容：
```json
{
@@ -179,7 +181,7 @@ curl "http://127.0.0.1:9080/anything";
}
```
-这验证了 Loki 已从 APISIX 接收日志。您还可以在 Grafana 中创建仪表板，以进一步可视化和分析日志。
+这验证了 Loki 已从 APISIX 接收日志。你还可以在 Grafana 中创建仪表板，以进一步可视化和分析日志。
### 使用 Plugin Metadata 自定义日志格式
@@ -228,9 +230,9 @@ curl
"http://127.0.0.1:9180/apisix/admin/plugin_metadata/loki-logger"; -X PUT \
curl -i "http://127.0.0.1:9080/anything";
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+你应该会收到 `HTTP/1.1 200 OK` 响应。
-导航到 [Grafana explore view](http://localhost:3000/explore) 并运行查询 `job =
apisix`。您应该会看到与您的请求相对应的日志条目，类似于以下内容：
+导航到 [Grafana explore view](http://localhost:3000/explore) 并运行查询 `job =
apisix`。你应该会看到与你的请求相对应的日志条目，类似于以下内容：
```json
{
@@ -265,9 +267,9 @@ curl
"http://127.0.0.1:9180/apisix/admin/routes/loki-logger-route"; -X PATCH \
curl -i "http://127.0.0.1:9080/anything";
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+你应该会收到 `HTTP/1.1 200 OK` 响应。
-导航到 [Grafana explore view](http://localhost:3000/explore) 并重新运行查询 `job =
apisix`。您应该会看到与您的请求相对应的日志条目，与路由上配置的格式一致，类似于以下内容：
+导航到 [Grafana explore view](http://localhost:3000/explore) 并重新运行查询 `job =
apisix`。你应该会看到与你的请求相对应的日志条目，与路由上配置的格式一致，类似于以下内容：
```json
{
@@ -311,9 +313,9 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl -i "http://127.0.0.1:9080/anything?log_body=yes"; -X POST -d '{"env":
"dev"}'
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+你应该会收到 `HTTP/1.1 200 OK` 响应。
-导航到 [Grafana explore view](http://localhost:3000/explore) 并重新运行查询 `job =
apisix`。您应该会看到与您的请求相对应的日志条目，与路由上配置的格式一致，类似于以下内容：
+导航到 [Grafana explore view](http://localhost:3000/explore) 并重新运行查询 `job =
apisix`。你应该会看到与你的请求相对应的日志条目，与路由上配置的格式一致，类似于以下内容：
```json
{
@@ -342,9 +344,9 @@ curl -i "http://127.0.0.1:9080/anything?log_body=yes"; -X
POST -d '{"env": "dev"}
curl -i "http://127.0.0.1:9080/anything"; -X POST -d '{"env": "dev"}'
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+你应该会收到 `HTTP/1.1 200 OK` 响应。
-导航到 [Grafana explore view](http://localhost:3000/explore) 并重新运行查询 `job =
apisix`。您应该会看到与您的请求相对应的日志条目，与路由上配置的格式一致，类似于以下内容：
+导航到 [Grafana explore view](http://localhost:3000/explore) 并重新运行查询 `job =
apisix`。你应该会看到与你的请求相对应的日志条目，与路由上配置的格式一致，类似于以下内容：
```json
{
@@ -366,13 +368,13 @@ curl -i "http://127.0.0.1:9080/anything"; -X POST -d
'{"env": "dev"}'
:::info
-如果您除了将 `include_req_body` 或 `include_resp_body` 设置为 `true` 之外还自定义了
`log_format`，则插件不会在日志中包含正文。
+如果你除了将 `include_req_body` 或 `include_resp_body` 设置为 `true` 之外还自定义了
`log_format`，则插件不会在日志中包含正文。
-作为一种解决方法，您可以在日志格式中使用 NGINX 变量 `$request_body`，例如：
+作为一种解决方法，你可以在日志格式中使用 NGINX 变量 `$request_body`，例如：
```json
{
- "kafka-logger": {
+ "loki-logger": {
...,
"log_format": {"body": "$request_body"}
}
