From 4061b9d077761118896327ef066b827e20c6c8c8 Mon Sep 17 00:00:00 2001 From: TaeyeongKwak Date: Wed, 22 Oct 2025 08:22:01 +0900 Subject: [PATCH 1/5] feat: add nested log format support for logger plugins --- apisix/utils/log-util.lua | 17 +++++- t/plugin/file-logger.t | 91 +++++++++++++++++++++++++++++++ t/plugin/http-logger-log-format.t | 75 +++++++++++++++++++++++++ 3 files changed, 180 insertions(+), 3 deletions(-) diff --git a/apisix/utils/log-util.lua b/apisix/utils/log-util.lua index 348c128dc2f6..31cca0ef6f86 100644 --- a/apisix/utils/log-util.lua +++ b/apisix/utils/log-util.lua @@ -72,7 +72,10 @@ end local function gen_log_format(format) local log_format = {} for k, var_name in pairs(format) do - if var_name:byte(1, 1) == str_byte("$") then + if type(var_name) == "table" then + local nested_format = gen_log_format(var_name) + log_format[k] = {false, nested_format} + elseif type(var_name) == "string" and var_name:byte(1, 1) == str_byte("$") then log_format[k] = {true, var_name:sub(2)} else log_format[k] = {false, var_name} @@ -83,8 +86,7 @@ local function gen_log_format(format) end -local function get_custom_format_log(ctx, format, max_req_body_bytes) - local log_format = lru_log_format(format or "", nil, gen_log_format, format) +local function build_log_entry(ctx, log_format, max_req_body_bytes) local entry = core.table.new(0, core.table.nkeys(log_format)) for k, var_attr in pairs(log_format) do if var_attr[1] then @@ -100,10 +102,19 @@ local function get_custom_format_log(ctx, format, max_req_body_bytes) else entry[k] = ctx.var[var_attr[2]] end + elseif type(var_attr[2]) == "table" then + entry[k] = build_log_entry(ctx, var_attr[2], max_req_body_bytes) else entry[k] = var_attr[2] end end + return entry +end + + +local function get_custom_format_log(ctx, format, max_req_body_bytes) + local log_format = lru_log_format(format or "", nil, gen_log_format, format) + local entry = build_log_entry(ctx, log_format, max_req_body_bytes) local matched_route = ctx.matched_route and ctx.matched_route.value if matched_route then diff --git a/t/plugin/file-logger.t b/t/plugin/file-logger.t index 30b9fc18a001..14181a753c05 100644 --- a/t/plugin/file-logger.t +++ b/t/plugin/file-logger.t @@ -338,3 +338,94 @@ passed } --- response_body write file log success + + + +=== TEST 10: nested log format in plugin +--- config + location /t { + content_by_lua_block { + local t = require("lib.test_admin").test + local code, body = t('/apisix/admin/routes/1', + ngx.HTTP_PUT, + [[{ + "plugins": { + "file-logger": { + "path": "file-logger-nested.log", + "log_format": { + "host": "$host", + "client_ip": "$remote_addr", + "request": { + "method": "$request_method", + "uri": "$request_uri", + "headers": { + "user_agent": "$http_user_agent" + } + }, + "response": { + "status": "$status" + } + } + } + }, + "upstream": { + "nodes": { + "127.0.0.1:1982": 1 + }, + "type": "roundrobin" + }, + "uri": "/hello" + }]] + ) + + if code >= 300 then + ngx.status = code + end + ngx.say(body) + } + } +--- response_body +passed + + + +=== TEST 11: verify nested log format structure +--- config + location /t { + content_by_lua_block { + local core = require("apisix.core") + local t = require("lib.test_admin").test + local code = t("/hello", ngx.HTTP_GET) + local fd, err = io.open("file-logger-nested.log", 'r') + local msg + + if not fd then + core.log.error("failed to open file: file-logger-nested.log, error info: ", err) + return + end + + msg = fd:read() + fd:close() + + local new_msg = core.json.decode(msg) + if new_msg.host == '127.0.0.1' and + new_msg.client_ip == '127.0.0.1' and + type(new_msg.request) == "table" and + new_msg.request.method == 'GET' and + new_msg.request.uri == '/hello' and + type(new_msg.request.headers) == "table" and + new_msg.request.headers.user_agent and + type(new_msg.response) == "table" and + new_msg.response.status == 200 and + new_msg.route_id == '1' + then + msg = "nested log format success" + ngx.status = code + ngx.say(msg) + else + ngx.say("nested log format failed") + end + } + } +--- response_body +nested log format success diff --git a/t/plugin/http-logger-log-format.t b/t/plugin/http-logger-log-format.t index 0bc8ceab31fa..1594580ce87a 100644 --- a/t/plugin/http-logger-log-format.t +++ b/t/plugin/http-logger-log-format.t @@ -567,3 +567,78 @@ passed tail -n 1 ci/pod/vector/http.log --- response_body eval qr/"x_ip":"127.0.0.1".*\}/ + + + +=== TEST 19: nested log format in plugin +--- config + location /t { + content_by_lua_block { + local t = require("lib.test_admin").test + local code, body = t('/apisix/admin/routes/1', + ngx.HTTP_PUT, + [[{ + "plugins": { + "http-logger": { + "uri": "http://127.0.0.1:3001", + "batch_max_size": 1, + "max_retry_count": 1, + "retry_delay": 2, + "buffer_duration": 2, + "inactive_timeout": 2, + "concat_method": "json", + "log_format": { + "host": "$host", + "client_ip": "$remote_addr", + "request": { + "method": "$request_method", + "uri": "$request_uri", + "headers": { + "user_agent": "$http_user_agent" + } + }, + "response": { + "status": "$status" + } + } + } + }, + "upstream": { + "nodes": { + "127.0.0.1:1982": 1 + }, + "type": "roundrobin" + }, + "uri": "/hello" + }]] + ) + + if code >= 300 then + ngx.status = code + end + + local code, _, body2 = t("/hello", "GET") + if code >= 300 then + ngx.status = code + ngx.say("fail") + return + end + ngx.say(body) + } + } +--- request +GET /t +--- response_body +passed + + + +=== TEST 20: hit route and verify nested log format +--- exec +tail -n 1 ci/pod/vector/http.log +--- response_body eval +qr/"client_ip":"127\.0\.0\.1"/ and +qr/"request":\{[^}]*"method":"GET"/ and +qr/"request":\{[^}]*"uri":"\/hello"/ and +qr/"response":\{[^}]*"status":200/ and +qr/"host":"127\.0\.0\.1"/ \ No newline at end of file From f55799705395146b820ccd342a5660647aa8e42b Mon Sep 17 00:00:00 2001 From: TaeyeongKwak Date: Tue, 28 Oct 2025 22:58:44 +0900 Subject: [PATCH 2/5] fix: update for lint --- apisix/utils/log-util.lua | 1 + t/plugin/file-logger.t | 2 +- t/plugin/http-logger-log-format.t | 6 +++--- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/apisix/utils/log-util.lua b/apisix/utils/log-util.lua index 31cca0ef6f86..9325769eb2be 100644 --- a/apisix/utils/log-util.lua +++ b/apisix/utils/log-util.lua @@ -20,6 +20,7 @@ local expr = require("resty.expr.v1") local content_decode = require("apisix.utils.content-decode") local ngx = ngx local pairs = pairs +local type = type local ngx_now = ngx.now local ngx_header = ngx.header local os_date = os.date diff --git a/t/plugin/file-logger.t b/t/plugin/file-logger.t index 14181a753c05..71b9d5af9bf9 100644 --- a/t/plugin/file-logger.t +++ b/t/plugin/file-logger.t @@ -408,7 +408,7 @@ passed fd:close() local new_msg = core.json.decode(msg) - if new_msg.host == '127.0.0.1' and + if new_msg.host == '127.0.0.1' and new_msg.client_ip == '127.0.0.1' and type(new_msg.request) == "table" and new_msg.request.method == 'GET' and diff --git a/t/plugin/http-logger-log-format.t b/t/plugin/http-logger-log-format.t index 1594580ce87a..e01330933cc0 100644 --- a/t/plugin/http-logger-log-format.t +++ b/t/plugin/http-logger-log-format.t @@ -637,8 +637,8 @@ passed --- exec tail -n 1 ci/pod/vector/http.log --- response_body eval -qr/"client_ip":"127\.0\.0\.1"/ and -qr/"request":\{[^}]*"method":"GET"/ and +qr/"client_ip":"127\.0\.0\.1"/ and +qr/"request":\{[^}]*"method":"GET"/ and qr/"request":\{[^}]*"uri":"\/hello"/ and qr/"response":\{[^}]*"status":200/ and -qr/"host":"127\.0\.0\.1"/ \ No newline at end of file +qr/"host":"127\.0\.0\.1"/ From 26d38c4665db8577b8cdcda0aaafbf05407615ab Mon Sep 17 00:00:00 2001 From: TaeyeongKwak Date: Wed, 29 Oct 2025 07:55:34 +0900 Subject: [PATCH 3/5] feat: enforce max depth for nested log_format --- apisix/utils/log-util.lua | 18 +++++-- t/plugin/file-logger.t | 70 +++++++++++++++++++++++++++ t/plugin/http-logger-log-format.t | 79 +++++++++++++++++++++++++++++++ 3 files changed, 164 insertions(+), 3 deletions(-) diff --git a/apisix/utils/log-util.lua b/apisix/utils/log-util.lua index 9325769eb2be..828038b78f15 100644 --- a/apisix/utils/log-util.lua +++ b/apisix/utils/log-util.lua @@ -33,6 +33,7 @@ local is_http = ngx.config.subsystem == "http" local req_get_body_file = ngx.req.get_body_file local MAX_REQ_BODY = 524288 -- 512 KiB local MAX_RESP_BODY = 524288 -- 512 KiB +local MAX_LOG_FORMAT_DEPTH = 5 local io = io local lru_log_format = core.lrucache.new({ @@ -70,18 +71,29 @@ local function get_request_body(max_bytes) end -local function gen_log_format(format) +local function do_gen_log_format(format, depth) local log_format = {} for k, var_name in pairs(format) do if type(var_name) == "table" then - local nested_format = gen_log_format(var_name) - log_format[k] = {false, nested_format} + if depth >= MAX_LOG_FORMAT_DEPTH then + core.log.warn("log_format nesting exceeds max depth ", + MAX_LOG_FORMAT_DEPTH, ", truncating") + log_format[k] = {false, {}} + else + local nested_format = do_gen_log_format(var_name, depth + 1) + log_format[k] = {false, nested_format} + end elseif type(var_name) == "string" and var_name:byte(1, 1) == str_byte("$") then log_format[k] = {true, var_name:sub(2)} else log_format[k] = {false, var_name} end end + return log_format +end + +local function gen_log_format(format) + local log_format = do_gen_log_format(format, 1) core.log.info("log_format: ", core.json.delay_encode(log_format)) return log_format end diff --git a/t/plugin/file-logger.t b/t/plugin/file-logger.t index 71b9d5af9bf9..cc07b88ef262 100644 --- a/t/plugin/file-logger.t +++ b/t/plugin/file-logger.t @@ -429,3 +429,73 @@ passed } --- response_body nested log format success + + + +=== TEST 12: deep nested log_format is truncated and warns +--- config + location /t { + content_by_lua_block { + local core = require("apisix.core") + local t = require("lib.test_admin").test + -- configure deep nested log_format + local code, body = t('/apisix/admin/routes/1', + ngx.HTTP_PUT, + [[{ + "plugins": { + "file-logger": { + "path": "file-logger-depth.log", + "log_format": { + "a": {"b": {"c": {"d": {"e": {"f": {"g": "$host"}}}}}} + } + } + }, + "upstream": { + "nodes": { + "127.0.0.1:1982": 1 + }, + "type": "roundrobin" + }, + "uri": "/hello" + }]] + ) + + if code >= 300 then + ngx.status = code + ngx.say(body) + return + end + + -- trigger logging + local code2 = t("/hello", ngx.HTTP_GET) + + -- read and verify depth truncation + local fd, err = io.open("file-logger-depth.log", 'r') + if not fd then + core.log.error("failed to open file: file-logger-depth.log, error info: ", err) + return + end + + local msg = fd:read() + fd:close() + + local new_msg = core.json.decode(msg) + local ok = type(new_msg.a) == "table" and + type(new_msg.a.b) == "table" and + type(new_msg.a.b.c) == "table" and + type(new_msg.a.b.c.d) == "table" and + type(new_msg.a.b.c.d.e) == "table" and + new_msg.a.b.c.d.e.f == nil + + if ok then + ngx.status = code2 + ngx.say("depth limit enforced") + else + ngx.say("depth limit not enforced") + end + } + } +--- response_body +depth limit enforced +--- error_log +log_format nesting exceeds max depth 5, truncating diff --git a/t/plugin/http-logger-log-format.t b/t/plugin/http-logger-log-format.t index e01330933cc0..ac42fa61ea43 100644 --- a/t/plugin/http-logger-log-format.t +++ b/t/plugin/http-logger-log-format.t @@ -642,3 +642,82 @@ qr/"request":\{[^}]*"method":"GET"/ and qr/"request":\{[^}]*"uri":"\/hello"/ and qr/"response":\{[^}]*"status":200/ and qr/"host":"127\.0\.0\.1"/ + + + +=== TEST 21: deep nested log_format is truncated and warns +--- config + location /t { + content_by_lua_block { + local core = require("apisix.core") + local t = require("lib.test_admin").test + -- configure deep nested log_format for http-logger + local code, body = t('/apisix/admin/routes/1', + ngx.HTTP_PUT, + [[{ + "plugins": { + "http-logger": { + "uri": "http://127.0.0.1:3001", + "batch_max_size": 1, + "max_retry_count": 1, + "retry_delay": 1, + "buffer_duration": 1, + "inactive_timeout": 1, + "concat_method": "json", + "log_format": { + "a": {"b": {"c": {"d": {"e": {"f": {"g": "$host"}}}}}} + } + } + }, + "upstream": { + "nodes": { + "127.0.0.1:1982": 1 + }, + "type": "roundrobin" + }, + "uri": "/hello" + }]] + ) + + if code >= 300 then + ngx.status = code + ngx.say(body) + return + end + + -- trigger logging + local code2 = t("/hello", ngx.HTTP_GET) + + -- wait for the batch processor to flush the log entry + ngx.sleep(1.1) + + -- read last log line from vector http log + local fd, err = io.open("ci/pod/vector/http.log", 'r') + if not fd then + core.log.error("failed to open file: ci/pod/vector/http.log, error info: ", err) + return + end + + local last + for line in fd:lines() do + last = line + end + fd:close() + + local has_chain = last and last:find('"a"%s*:%s*%{"b"%s*:%s*%{"c"%s*:%s*%{"d"%s*:%s*%{"e"%s*:%s*%{') + local has_f = last and last:find('\"f\"%s*:') + + if has_chain and not has_f then + ngx.status = code2 + ngx.say("http depth limit enforced") + else + ngx.say("http depth limit not enforced") + end + } + } +--- request +GET /t +--- response_body +http depth limit enforced +--- error_log +log_format nesting exceeds max depth 5, truncating From 478ef32152bda4e383a36d124fd0f6cd10e7b614 Mon Sep 17 00:00:00 2001 From: TaeyeongKwak Date: Wed, 29 Oct 2025 08:40:29 +0900 Subject: [PATCH 4/5] docs: update the logger plugin docs --- docs/en/latest/plugins/clickhouse-logger.md | 4 ++-- docs/en/latest/plugins/elasticsearch-logger.md | 4 ++-- docs/en/latest/plugins/file-logger.md | 17 ++++++++++++----- docs/en/latest/plugins/google-cloud-logging.md | 10 ++++++---- docs/en/latest/plugins/http-logger.md | 12 +++++++----- docs/en/latest/plugins/kafka-logger.md | 12 +++++++----- docs/en/latest/plugins/loggly.md | 4 ++-- docs/en/latest/plugins/loki-logger.md | 4 ++-- docs/en/latest/plugins/rocketmq-logger.md | 12 +++++++----- docs/en/latest/plugins/skywalking-logger.md | 4 ++-- docs/en/latest/plugins/sls-logger.md | 12 +++++++----- docs/en/latest/plugins/splunk-hec-logging.md | 10 ++++++---- docs/en/latest/plugins/syslog.md | 12 +++++++----- docs/en/latest/plugins/tcp-logger.md | 10 ++++++---- docs/en/latest/plugins/tencent-cloud-cls.md | 12 +++++++----- docs/en/latest/plugins/udp-logger.md | 10 ++++++---- docs/zh/latest/plugins/clickhouse-logger.md | 4 ++-- docs/zh/latest/plugins/elasticsearch-logger.md | 4 ++-- docs/zh/latest/plugins/file-logger.md | 12 +++++++----- docs/zh/latest/plugins/google-cloud-logging.md | 10 ++++++---- docs/zh/latest/plugins/http-logger.md | 12 +++++++----- docs/zh/latest/plugins/kafka-logger.md | 12 +++++++----- docs/zh/latest/plugins/loggly.md | 4 ++-- docs/zh/latest/plugins/loki-logger.md | 4 ++-- docs/zh/latest/plugins/rocketmq-logger.md | 12 +++++++----- docs/zh/latest/plugins/skywalking-logger.md | 4 ++-- docs/zh/latest/plugins/sls-logger.md | 12 +++++++----- docs/zh/latest/plugins/splunk-hec-logging.md | 10 ++++++---- docs/zh/latest/plugins/syslog.md | 4 ++-- docs/zh/latest/plugins/tcp-logger.md | 10 ++++++---- docs/zh/latest/plugins/tencent-cloud-cls.md | 12 +++++++----- docs/zh/latest/plugins/udp-logger.md | 10 ++++++---- 32 files changed, 166 insertions(+), 119 deletions(-) diff --git a/docs/en/latest/plugins/clickhouse-logger.md b/docs/en/latest/plugins/clickhouse-logger.md index 023f9e920bcd..498b242d1db2 100644 --- a/docs/en/latest/plugins/clickhouse-logger.md +++ b/docs/en/latest/plugins/clickhouse-logger.md @@ -44,7 +44,7 @@ The `clickhouse-logger` Plugin is used to push logs to [ClickHouse](https://clic | timeout | integer | False | 3 | [1,...] | Time to keep the connection alive for after sending a request. | | name | string | False | "clickhouse logger" | | Unique identifier for the logger. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. | | ssl_verify | boolean | False | true | [true,false] | When set to `true`, verifies SSL. | -| log_format | object | False | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitations. | | include_req_body_expr | array | False | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | | include_resp_body | boolean | False | false | [false, true] | When set to `true` includes the response body in the log. | @@ -103,7 +103,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT diff --git a/docs/en/latest/plugins/elasticsearch-logger.md b/docs/en/latest/plugins/elasticsearch-logger.md index 80ea0760163e..7ef37d334833 100644 --- a/docs/en/latest/plugins/elasticsearch-logger.md +++ b/docs/en/latest/plugins/elasticsearch-logger.md @@ -42,7 +42,7 @@ The `elasticsearch-logger` Plugin pushes request and response logs in batches to | 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 in key-value pairs in JSON format. Support [APISIX](../apisix-variable.md) or [NGINX variables](http://nginx.org/en/docs/varindex.html) in values. | +| 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. | @@ -61,7 +61,7 @@ This Plugin supports using batch processors to aggregate and process entries (lo | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| -| log_format | object | False | | Custom log format in key-value pairs in JSON format. Support [APISIX variables](../apisix-variable.md) and [NGINX variables](http://nginx.org/en/docs/varindex.html) in values. | +| 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 `$`. | ## Examples diff --git a/docs/en/latest/plugins/file-logger.md b/docs/en/latest/plugins/file-logger.md index 05f2d49fd7f7..44821301667e 100644 --- a/docs/en/latest/plugins/file-logger.md +++ b/docs/en/latest/plugins/file-logger.md @@ -46,7 +46,7 @@ The `file-logger` Plugin is used to push log streams to a specific location. | Name | Type | Required | Description | | ---- | ------ | -------- | ------------- | | path | string | True | Log file path. | -| log_format | object | False | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | include_req_body | boolean | False | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitations. | | include_req_body_expr | array | False | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | | include_resp_body | boolean | False | When set to `true` includes the response body in the log file. | @@ -103,7 +103,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | The example below shows how you can configure through the Admin API: @@ -122,7 +122,14 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/file-logger -H "X-API-KE "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { + "method": "$request_method", + "uri": "$request_uri" + }, + "response": { + "status": "$status" + } } }' ``` @@ -130,8 +137,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/file-logger -H "X-API-KE With this configuration, your logs would be formatted as shown below: ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/google-cloud-logging.md b/docs/en/latest/plugins/google-cloud-logging.md index 85b972381c5c..f0721b61ed03 100644 --- a/docs/en/latest/plugins/google-cloud-logging.md +++ b/docs/en/latest/plugins/google-cloud-logging.md @@ -48,7 +48,7 @@ This plugin also allows to push logs as a batch to your Google Cloud Logging Ser | ssl_verify | False | true | When set to `true`, enables SSL verification as mentioned in [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | | resource | False | {"type": "global"} | Google monitor resource. See [MonitoredResource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource) for more details. | | log_id | False | apisix.apache.org%2Flogs | Google Cloud logging ID. See [LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry) for details. | -| log_format | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | NOTE: `encrypt_fields = {"auth_config.private_key"}` 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). @@ -90,7 +90,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -115,7 +115,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/google-cloud-logging -H "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -123,7 +125,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/google-cloud-logging -H With this configuration, your logs would be formatted as shown below: ```json -{"partialSuccess":false,"entries":[{"jsonPayload":{"client_ip":"127.0.0.1","host":"localhost","@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1"},"resource":{"type":"global"},"insertId":"942e81f60b9157f0d46bc9f5a8f0cc40","logName":"projects/apisix/logs/apisix.apache.org%2Flogs","timestamp":"2023-01-09T14:47:25+08:00","labels":{"source":"apache-apisix-google-cloud-logging"}}]} +{"partialSuccess":false,"entries":[{"jsonPayload":{"host":"localhost","client_ip":"127.0.0.1","@timestamp":"2023-01-09T14:47:25+08:00","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"},"resource":{"type":"global"},"insertId":"942e81f60b9157f0d46bc9f5a8f0cc40","logName":"projects/apisix/logs/apisix.apache.org%2Flogs","timestamp":"2023-01-09T14:47:25+08:00","labels":{"source":"apache-apisix-google-cloud-logging"}}]} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/http-logger.md b/docs/en/latest/plugins/http-logger.md index d07375b0bcea..b7f8aedc22b7 100644 --- a/docs/en/latest/plugins/http-logger.md +++ b/docs/en/latest/plugins/http-logger.md @@ -40,7 +40,7 @@ This will allow the ability to send log data requests as JSON objects to monitor | uri | string | True | | | URI of the HTTP/HTTPS server. | | auth_header | string | False | | | Authorization headers if required. | | timeout | integer | False | 3 | [1,...] | Time to keep the connection alive for after sending a request. | -| log_format | object | False | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitations. | | include_req_body_expr | array | False | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | | include_resp_body | boolean | False | false | [false, true] | When set to `true` includes the response body in the log. | @@ -104,7 +104,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -130,7 +130,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -138,8 +140,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger \ With this configuration, your logs would be formatted as shown below: ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/kafka-logger.md b/docs/en/latest/plugins/kafka-logger.md index a1a717c5e95e..bb1f7a0f1e49 100644 --- a/docs/en/latest/plugins/kafka-logger.md +++ b/docs/en/latest/plugins/kafka-logger.md @@ -52,7 +52,7 @@ It might take some time to receive the log data. It will be automatically sent a | timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. | | name | string | False | "kafka logger" | | Unique identifier for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. | | meta_format | enum | False | "default" | ["default"，"origin"] | Format to collect the request information. Setting to `default` collects the information in JSON format and `origin` collects the information with the original HTTP request. See [examples](#meta_format-example) below. | -| log_format | object | False | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitations. | | include_req_body_expr | array | False | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | | max_req_body_bytes | integer | False | 524288 | >=1 | Maximum request body allowed in bytes. Request bodies falling within this limit will be pushed to Kafka. If the size exceeds the configured value, the body will be truncated before being pushed to Kafka. | @@ -138,7 +138,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -163,7 +163,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/kafka-logger -H "X-API-K "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -171,8 +173,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/kafka-logger -H "X-API-K With this configuration, your logs would be formatted as shown below: ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/loggly.md b/docs/en/latest/plugins/loggly.md index a1838c2366f1..3899dca37c85 100644 --- a/docs/en/latest/plugins/loggly.md +++ b/docs/en/latest/plugins/loggly.md @@ -43,7 +43,7 @@ When the maximum batch size is exceeded, the data in the queue is pushed to Logg | severity | string (enum) | False | INFO | Syslog log event severity level. Choose between: `DEBUG`, `INFO`, `NOTICE`, `WARNING`, `ERR`, `CRIT`, `ALERT`, and `EMEGR`. | | severity_map | object | False | nil | A way to map upstream HTTP response codes to Syslog severity. Key-value pairs where keys are the HTTP response codes and the values are the Syslog severity levels. For example `{"410": "CRIT"}`. | | tags | array | False | | Metadata to be included with any event log to aid in segmentation and filtering. | -| log_format | object | False | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | include_req_body | boolean | False | false | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitations. | | include_req_body_expr | array | False | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | | include_resp_body | boolean | False | false | When set to `true` includes the response body in the log. | @@ -69,7 +69,7 @@ You can also configure the Plugin through Plugin metadata. The following configu | port | integer | False | 514 | | Loggly port to connect to. Only used for `syslog` protocol. | | timeout | integer | False | 5000 | | Loggly send data request timeout in milliseconds. | | protocol | string | False | "syslog" | [ "syslog" , "http", "https" ] | Protocol in which the logs are sent to Loggly. | -| log_format | object | False | nil | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | nil | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | We support [Syslog](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/streaming-syslog-without-using-files.htm), [HTTP/S](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/http-bulk-endpoint.htm) (bulk endpoint) protocols to send log events to Loggly. By default, in APISIX side, the protocol is set to "syslog". It lets you send RFC5424 compliant syslog events with some fine-grained control (log severity mapping based on upstream HTTP response code). But HTTP/S bulk endpoint is great to send larger batches of log events with faster transmission speed. If you wish to update it, just update the metadata. diff --git a/docs/en/latest/plugins/loki-logger.md b/docs/en/latest/plugins/loki-logger.md index 65a0a86d7e74..3e578e05b312 100644 --- a/docs/en/latest/plugins/loki-logger.md +++ b/docs/en/latest/plugins/loki-logger.md @@ -52,7 +52,7 @@ When enabled, the Plugin will serialize the request context information to [JSON | keepalive | boolean | False | true | | If true, keep the connection alive for multiple requests. | | keepalive_timeout | integer | False | 60000 | >=1000 | Keepalive timeout in milliseconds. | | keepalive_pool | integer | False | 5 | >=1 | Maximum number of connections in the connection pool. | -| log_format | object | False | | | Custom log format in key-value pairs in JSON format. Support [APISIX variables](../apisix-variable.md) and [NGINX variables](http://nginx.org/en/docs/varindex.html) in values. | +| 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 `$`. | | name | string | False | loki-logger | | Unique identifier of the Plugin for the batch processor. If you use [Prometheus](./prometheus.md) to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. | | 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. | @@ -67,7 +67,7 @@ You can also configure log format on a global scale using the [Plugin Metadata]( | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| -| log_format | object | False | | Custom log format in key-value pairs in JSON format. Support [APISIX variables](../apisix-variable.md) and [NGINX variables](http://nginx.org/en/docs/varindex.html) in values. | +| 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 `$`. | ## Examples diff --git a/docs/en/latest/plugins/rocketmq-logger.md b/docs/en/latest/plugins/rocketmq-logger.md index ff09c668eb1c..5e9ba61ae874 100644 --- a/docs/en/latest/plugins/rocketmq-logger.md +++ b/docs/en/latest/plugins/rocketmq-logger.md @@ -40,7 +40,7 @@ It might take some time to receive the log data. It will be automatically sent a | topic | string | True | | | Target topic to push the data to. | | key | string | False | | | Key of the messages. | | tag | string | False | | | Tag of the messages. | -| log_format | object | False | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. | | use_tls | boolean | False | false | | When set to `true`, uses TLS. | | access_key | string | False | "" | | Access key for ACL. Setting to an empty string will disable the ACL. | @@ -181,7 +181,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | |------------|--------|----------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -206,7 +206,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/rocketmq-logger -H "X-AP "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -214,8 +216,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/rocketmq-logger -H "X-AP With this configuration, your logs would be formatted as shown below: ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/skywalking-logger.md b/docs/en/latest/plugins/skywalking-logger.md index bb0532a2a72a..8d0c40083d5c 100644 --- a/docs/en/latest/plugins/skywalking-logger.md +++ b/docs/en/latest/plugins/skywalking-logger.md @@ -45,7 +45,7 @@ If there is an existing tracing context, it sets up the trace-log correlation au | endpoint_addr | string | True | | | URI of the SkyWalking OAP server. | | service_name | string | False | "APISIX" | | Service name for the SkyWalking reporter. | | service_instance_name | string | False | "APISIX Instance Name" | | Service instance name for the SkyWalking reporter. Set it to `$hostname` to directly get the local hostname. | -| log_format | object | False | | Custom log format in key-value pairs in JSON format. Support [APISIX](../apisix-variable.md) or [Nginx variables](http://nginx.org/en/docs/varindex.html) in values if the string starts with `$`. | +| 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 `$`. | | timeout | integer | False | 3 | [1,...] | Time to keep the connection alive for after sending a request. | | name | string | False | "skywalking logger" | | Unique identifier to identify the logger. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. | | 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. | @@ -61,7 +61,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Custom log format in key-value pairs in JSON format. Support [APISIX](../apisix-variable.md) or [NGINX variables](http://nginx.org/en/docs/varindex.html) in values. | +| 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 `$`. | ## Examples diff --git a/docs/en/latest/plugins/sls-logger.md b/docs/en/latest/plugins/sls-logger.md index d779386fa234..d2c5b51f98d9 100644 --- a/docs/en/latest/plugins/sls-logger.md +++ b/docs/en/latest/plugins/sls-logger.md @@ -40,7 +40,7 @@ It might take some time to receive the log data. It will be automatically sent a | host | True | IP address or the hostname of the TCP server. See [Alibaba Cloud log service documentation](https://www.alibabacloud.com/help/en/log-service/latest/endpoints) for details. Use IP address instead of domain. | | port | True | Target upstream port. Defaults to `10009`. | | timeout | False | Timeout for the upstream to send data. | -| log_format | False | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | False | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | project | True | Project name in Alibaba Cloud log service. Create SLS before using this Plugin. | | logstore | True | logstore name in Ali Cloud log service. Create SLS before using this Plugin. | | access_key_id | True | AccessKey ID in Alibaba Cloud. See [Authorization](https://www.alibabacloud.com/help/en/log-service/latest/create-a-ram-user-and-authorize-the-ram-user-to-access-log-service) for more details. | @@ -88,7 +88,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -113,7 +113,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/sls-logger -H "X-API-KEY "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -121,8 +123,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/sls-logger -H "X-API-KEY With this configuration, your logs would be formatted as shown below: ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/splunk-hec-logging.md b/docs/en/latest/plugins/splunk-hec-logging.md index 565f84e4bc67..a7ca1389ded6 100644 --- a/docs/en/latest/plugins/splunk-hec-logging.md +++ b/docs/en/latest/plugins/splunk-hec-logging.md @@ -45,7 +45,7 @@ When the Plugin is enabled, APISIX will serialize the request context informatio | endpoint.timeout | False | 10 | Splunk HEC send data timeout in seconds. | | endpoint.keepalive_timeout | False | 60000 | Keepalive timeout in milliseconds. | | ssl_verify | False | true | When set to `true` enables SSL verification as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | -| log_format | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | This Plugin supports using batch processors to aggregate and process entries (logs/data) in a batch. This avoids the need for frequently submitting the data. The batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. See [Batch Processor](../batch-processor.md#configuration) for more information or setting your custom configuration. @@ -86,7 +86,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -111,7 +111,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/splunk-hec-logging -H "X "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -119,7 +121,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/splunk-hec-logging -H "X With this configuration, your logs would be formatted as shown below: ```json -[{"time":1673976669.269,"source":"apache-apisix-splunk-hec-logging","event":{"host":"localhost","client_ip":"127.0.0.1","@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1"},"host":"DESKTOP-2022Q8F-wsl","sourcetype":"_json"}] +[{"time":1673976669.269,"source":"apache-apisix-splunk-hec-logging","event":{"host":"localhost","client_ip":"127.0.0.1","@timestamp":"2023-01-09T14:47:25+08:00","request":{"method":"GET","uri":"/splunk.do"},"response":{"status":200},"route_id":"1"},"host":"DESKTOP-2022Q8F-wsl","sourcetype":"_json"}] ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/syslog.md b/docs/en/latest/plugins/syslog.md index 8cba65e0eccb..7acb7f3b1a31 100644 --- a/docs/en/latest/plugins/syslog.md +++ b/docs/en/latest/plugins/syslog.md @@ -45,7 +45,7 @@ Logs can be set as JSON objects. | drop_limit | integer | False | 1048576 | | Maximum size of the buffer (KB) and the current message before the current message is dropped because of the size limit. | | sock_type | string | False | "tcp" | ["tcp", "udp] | Transport layer protocol to use. | | pool_size | integer | False | 5 | [5, ...] | Keep-alive pool size used by `sock:keepalive`. | -| log_format | object | False | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. | | include_req_body_expr | array | False | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | | include_resp_body | boolean | False | false | [false, true] | When set to `true` includes the response body in the log. | @@ -65,7 +65,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -90,7 +90,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/syslog -H "X-API-KEY: $a "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -98,8 +100,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/syslog -H "X-API-KEY: $a With this configuration, your logs would be formatted as shown below: ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/tcp-logger.md b/docs/en/latest/plugins/tcp-logger.md index 53fd43e6609f..adc7efa3dd1e 100644 --- a/docs/en/latest/plugins/tcp-logger.md +++ b/docs/en/latest/plugins/tcp-logger.md @@ -43,7 +43,7 @@ This plugin also allows to push logs as a batch to your external TCP server. It | host | string | True | | | IP address or the hostname of the TCP server. | | port | integer | True | | [0,...] | Target upstream port. | | timeout | integer | False | 1000 | [1,...] | Timeout for the upstream to send data. | -| log_format | object | False | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | tls | boolean | False | false | | When set to `true` performs SSL verification. | | tls_options | string | False | | | TLS options. | | include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. | @@ -99,7 +99,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -124,7 +124,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tcp-logger -H "X-API-KEY "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -132,7 +134,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tcp-logger -H "X-API-KEY With this configuration, your logs would be formatted as shown below: ```json -{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1"} +{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200}} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/tencent-cloud-cls.md b/docs/en/latest/plugins/tencent-cloud-cls.md index f1ee4c43d7d9..99ab4a5dc499 100644 --- a/docs/en/latest/plugins/tencent-cloud-cls.md +++ b/docs/en/latest/plugins/tencent-cloud-cls.md @@ -46,7 +46,7 @@ The `tencent-cloud-cls` Plugin uses [TencentCloud CLS](https://cloud.tencent.com | include_resp_body | boolean | No | false | [false, true] | When set to `true` includes the response body in the log. | | include_resp_body_expr | array | No | | | Filter for when the `include_resp_body` attribute is set to `true`. Response body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | | global_tag | object | No | | | kv pairs in JSON，send with each log. | -| log_format | object | No | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | No | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | NOTE: `encrypt_fields = {"secret_key"}` 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). @@ -98,7 +98,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -124,7 +124,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tencent-cloud-cls \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -132,8 +134,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tencent-cloud-cls \ With this configuration, your logs would be formatted as shown below: ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## Enable Plugin diff --git a/docs/en/latest/plugins/udp-logger.md b/docs/en/latest/plugins/udp-logger.md index 503566a07fd5..9b9d7c84a88a 100644 --- a/docs/en/latest/plugins/udp-logger.md +++ b/docs/en/latest/plugins/udp-logger.md @@ -42,7 +42,7 @@ This plugin also allows to push logs as a batch to your external UDP server. It | host | string | True | | | IP address or the hostname of the UDP server. | | port | integer | True | | [0,...] | Target upstream port. | | timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. | -| log_format | object | False | | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | | name | string | False | "udp logger" | | Unique identifier for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. processor. | | include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. | | include_req_body_expr | array | No | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. | @@ -97,7 +97,7 @@ You can also set the format of the logs by configuring the Plugin metadata. The | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| log_format | object | False | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. | :::info IMPORTANT @@ -122,7 +122,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/udp-logger -H "X-API-KEY "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -130,7 +132,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/udp-logger -H "X-API-KEY With this configuration, your logs would be formatted as shown below: ```json -{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1"} +{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200}} ``` ## Enable Plugin diff --git a/docs/zh/latest/plugins/clickhouse-logger.md b/docs/zh/latest/plugins/clickhouse-logger.md index f482f449d362..c64374e32ec3 100644 --- a/docs/zh/latest/plugins/clickhouse-logger.md +++ b/docs/zh/latest/plugins/clickhouse-logger.md @@ -44,7 +44,7 @@ description: 本文介绍了 API 网关 Apache APISIX 如何使用 clickhouse-lo | timeout | integer | 否 | 3 | [1,...] | 发送请求后保持连接活动的时间。 | | name | string | 否 | "clickhouse logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 | | ssl_verify | boolean | 否 | true | [true,false] | 当设置为 `true` 时，验证证书。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。| | include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 | | include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 | @@ -103,7 +103,7 @@ description: 本文介绍了 API 网关 Apache APISIX 如何使用 clickhouse-lo | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX](../apisix-variable.md) 或 [NGINX](http://nginx.org/en/docs/varindex.html) 变量。该配置全局生效。如果你指定了 `log_format`，该配置就会对所有绑定 `clickhouse-logger` 的路由或服务生效。| +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX](../apisix-variable.md) 或 [NGINX](http://nginx.org/en/docs/varindex.html) 变量。该配置全局生效。如果你指定了 `log_format`，该配置就会对所有绑定 `clickhouse-logger` 的路由或服务生效。| :::note diff --git a/docs/zh/latest/plugins/elasticsearch-logger.md b/docs/zh/latest/plugins/elasticsearch-logger.md index 362b579593b0..2b4b912c71ff 100644 --- a/docs/zh/latest/plugins/elasticsearch-logger.md +++ b/docs/zh/latest/plugins/elasticsearch-logger.md @@ -43,7 +43,7 @@ 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)。 | +| 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) 密码。 | @@ -62,7 +62,7 @@ description: elasticsearch-logger Plugin 将请求和响应日志批量推送到 | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| -| log_format | object | 否 | |自定义日志格式为 JSON 格式的键值对。值中支持 [APISIX 变量](../apisix-variable.md) 和 [NGINX 变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | 自定义日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过 `$` 前缀引用 [APISIX 变量](../apisix-variable.md) 和 [NGINX 变量](http://nginx.org/en/docs/varindex.html)。 | ## 示例 diff --git a/docs/zh/latest/plugins/file-logger.md b/docs/zh/latest/plugins/file-logger.md index c5953c251cad..2e4f084d6d53 100644 --- a/docs/zh/latest/plugins/file-logger.md +++ b/docs/zh/latest/plugins/file-logger.md @@ -48,7 +48,7 @@ description: API 网关 Apache APISIX file-logger 插件可用于将日志数据 | 名称 | 类型 | 必选项 | 描述 | | ---------------- | ------- |-----| ------------------------------------------------ | | path | string | 是 | 自定义输出文件路径。例如：`logs/file.log`。 | -| log_format | object | 否 | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | include_req_body | boolean | 否 | 当设置为 `true` 时，日志中将包含请求体。如果请求体太大而无法在内存中保存，则由于 Nginx 的限制，无法记录请求体。| | include_req_body_expr | array | 否 | 当 `include_req_body` 属性设置为 `true` 时的过滤器。只有当此处设置的表达式求值为 `true` 时，才会记录请求体。有关更多信息，请参阅 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 。 | | include_resp_body | boolean | 否 | 当设置为 `true` 时，生成的文件包含响应体。 | @@ -103,7 +103,7 @@ description: API 网关 Apache APISIX file-logger 插件可用于将日志数据 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 可选 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 可选 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::note 注意 @@ -130,7 +130,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/file-logger \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -138,8 +140,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/file-logger \ 配置完成后，你可以在日志系统中看到如下类似日志： ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## 启用插件 diff --git a/docs/zh/latest/plugins/google-cloud-logging.md b/docs/zh/latest/plugins/google-cloud-logging.md index d485bee31009..b3a27cd72a93 100644 --- a/docs/zh/latest/plugins/google-cloud-logging.md +++ b/docs/zh/latest/plugins/google-cloud-logging.md @@ -48,7 +48,7 @@ description: API 网关 Apache APISIX 的 google-cloud-logging 插件可用于 | ssl_verify | 否 | true | 当设置为 `true` 时，启用 `SSL` 验证。 | | resource | 否 | {"type": "global"} | 谷歌监控资源，请参考 [MonitoredResource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource)。 | | log_id | 否 | apisix.apache.org%2Flogs | 谷歌日志 ID，请参考 [LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry)。 | -| log_format | 否 | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | 注意：schema 中还定义了 `encrypt_fields = {"auth_config.private_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 @@ -88,7 +88,7 @@ description: API 网关 Apache APISIX 的 google-cloud-logging 插件可用于 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头。则表明获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::info 注意 @@ -115,7 +115,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/google-cloud-logging \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -123,7 +125,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/google-cloud-logging \ 配置完成后，你将在日志系统中看到如下类似日志： ```json -{"partialSuccess":false,"entries":[{"jsonPayload":{"client_ip":"127.0.0.1","host":"localhost","@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1"},"resource":{"type":"global"},"insertId":"942e81f60b9157f0d46bc9f5a8f0cc40","logName":"projects/apisix/logs/apisix.apache.org%2Flogs","timestamp":"2023-01-09T14:47:25+08:00","labels":{"source":"apache-apisix-google-cloud-logging"}}]} +{"partialSuccess":false,"entries":[{"jsonPayload":{"host":"localhost","client_ip":"127.0.0.1","@timestamp":"2023-01-09T14:47:25+08:00","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"},"resource":{"type":"global"},"insertId":"942e81f60b9157f0d46bc9f5a8f0cc40","logName":"projects/apisix/logs/apisix.apache.org%2Flogs","timestamp":"2023-01-09T14:47:25+08:00","labels":{"source":"apache-apisix-google-cloud-logging"}}]} ``` ## 启用插件 diff --git a/docs/zh/latest/plugins/http-logger.md b/docs/zh/latest/plugins/http-logger.md index 1903ddd8b134..51fe1df39ddf 100644 --- a/docs/zh/latest/plugins/http-logger.md +++ b/docs/zh/latest/plugins/http-logger.md @@ -40,7 +40,7 @@ description: 本文介绍了 API 网关 Apache APISIX 的 http-logger 插件。 | uri | string | 是 | | | HTTP 或 HTTPS 服务器的 URI。 | | auth_header | string | 否 | | | 授权 header（如果需要）。 | | timeout | integer | 否 | 3 | [1,...] | 发送请求后保持连接处于活动状态的时间。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，将请求体包含在日志中。如果请求体太大而无法保存在内存中，由于 NGINX 的限制，无法记录。 | | include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时的过滤器。只有当此处设置的表达式求值为 `true` 时，才会记录请求体。有关更多信息，请参阅 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 。 | | include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 | @@ -98,7 +98,7 @@ description: 本文介绍了 API 网关 Apache APISIX 的 http-logger 插件。 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头。则表明获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::info 注意 @@ -125,7 +125,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -133,8 +135,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger \ 配置完成后，你将在日志系统中看到如下类似日志： ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## 启用插件 diff --git a/docs/zh/latest/plugins/kafka-logger.md b/docs/zh/latest/plugins/kafka-logger.md index e708a21b87e5..24f1ca4b65dd 100644 --- a/docs/zh/latest/plugins/kafka-logger.md +++ b/docs/zh/latest/plugins/kafka-logger.md @@ -50,7 +50,7 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作 | timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 | | name | string | 否 | "kafka logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 | | meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-示例)。| -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。| | include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 | | max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大请求正文（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 | @@ -134,7 +134,7 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作 | 名称 | 类型 | 必选项 | 默认值 | 描述 | | ---------------- | ------- | ------ | ------------- |------------------------------------------------ | -| log_format | object | 否 | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::note 注意 @@ -161,7 +161,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/kafka-logger \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -169,8 +171,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/kafka-logger \ 配置完成后，你将在日志系统中看到如下类似日志： ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## 如何启用 diff --git a/docs/zh/latest/plugins/loggly.md b/docs/zh/latest/plugins/loggly.md index e8b05af66d8f..09e599f7748d 100644 --- a/docs/zh/latest/plugins/loggly.md +++ b/docs/zh/latest/plugins/loggly.md @@ -41,7 +41,7 @@ description: API 网关 Apache APISIX loggly 插件可用于将日志转发到 S | severity | string (enum) | 否 | INFO | Syslog 日志事件的严重性级别。包括：`DEBUG`、`INFO`、`NOTICE`、`WARNING`、`ERR`、`CRIT`、`ALERT` 和 `EMEGR`。 | | severity_map | object | 否 | nil | 一种将上游 HTTP 响应代码映射到 Syslog 中的方法。 `key-value`，其中 `key` 是 HTTP 响应代码，`value`是 Syslog 严重级别。例如`{"410": "CRIT"}`。 | | tags | array | 否 | | 元数据将包含在任何事件日志中，以帮助进行分段和过滤。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | include_req_body | boolean | 否 | false | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。 | | include_req_body_expr | array | 否 | | 当 `include_req_body` 属性设置为 `true` 时的过滤器。只有当此处设置的表达式求值为 `true` 时，才会记录请求体。有关更多信息，请参阅 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 。 | | include_resp_body | boolean | 否 | false | 当设置为 `true` 时，包含响应体。 | @@ -67,7 +67,7 @@ description: API 网关 Apache APISIX loggly 插件可用于将日志转发到 S | port | integer | 否 | 514 | | 要连接的 Loggly 端口。仅用于 `syslog` 协议。 | | timeout | integer | 否 | 5000 | | 发送数据请求超时时间（以毫秒为单位）。 | | protocol | string | 否 | "syslog" | [ "syslog", "http", "https" ] | 将日志发送到 Loggly 的协议。 | -| log_format | object | 否 | nil | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | nil | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | APISIX 支持 [Syslog](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/streaming-syslog-without-using-files.htm)、[HTTP/S](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/http-bulk-endpoint.htm)（批量端点）协议将日志事件发送到 Loggly。**默认情况下 `protocol` 的值为 `syslog`**。该协议允许你通过一些细粒度的控制（基于上游 HTTP 响应代码的日志严重性映射）发送符合 RFC5424 的系统日志事件。但是 HTTP/S 批量端点非常适合以更快的传输速度发送更大量的日志事件。 diff --git a/docs/zh/latest/plugins/loki-logger.md b/docs/zh/latest/plugins/loki-logger.md index bc32dcad1179..78010fe1eb2c 100644 --- a/docs/zh/latest/plugins/loki-logger.md +++ b/docs/zh/latest/plugins/loki-logger.md @@ -52,7 +52,7 @@ description: loki-logger 插件通过 Loki HTTP API /loki/api/v1/push 将请求 | keepalive | boolean | 否 | true | | 如果为 true，则保持连接以应对多个请求。| | keepalive_timeout | integer | 否 | 60000 | >=1000 | Keepalive 超时时间（以毫秒为单位）。| | keepalive_pool | integer | 否 | 5 | >=1 | 连接池中的最大连接数。| -| log_format | object | 否 | | |自定义日志格式为 JSON 格式的键值对。值中支持 [APISIX 变量](../apisix-variable.md) 和 [NGINX 变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 自定义日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过 `$` 前缀引用 [APISIX 变量](../apisix-variable.md) 和 [NGINX 变量](http://nginx.org/en/docs/varindex.html)。 | | 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 时，才会记录请求正文。| @@ -67,7 +67,7 @@ description: loki-logger 插件通过 Loki HTTP API /loki/api/v1/push 将请求 | 名称 | 类型 | 必选项 | 默认值 | 描述 | |------|------|----------|--|-------------| -| log_format | object | 否 | | 日志格式以 JSON 格式声明为键值对。值只支持字符串类型。可以通过在字符串前面加上 `$` 来使用 [APISIX 变量](../apisix-variable.md) 和 [NGINX 变量](http://nginx.org/en/docs/varindex.html) 。 | +| log_format | object | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 和 [NGINX 变量](http://nginx.org/en/docs/varindex.html)。 | ## 示例 diff --git a/docs/zh/latest/plugins/rocketmq-logger.md b/docs/zh/latest/plugins/rocketmq-logger.md index 21d8e42845e5..6b6e1e4f8e58 100644 --- a/docs/zh/latest/plugins/rocketmq-logger.md +++ b/docs/zh/latest/plugins/rocketmq-logger.md @@ -39,7 +39,7 @@ description: API 网关 Apache APISIX 的 rocketmq-logger 插件用于将日志 | topic | string | 是 | | | 要推送的 topic 名称。 | | key | string | 否 | | | 发送消息的 keys。 | | tag | string | 否 | | | 发送消息的 tags。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 | | use_tls | boolean | 否 | false | | 当设置为 `true` 时，开启 TLS 加密。 | | access_key | string | 否 | "" | | ACL 认证的 Access key，空字符串表示不开启 ACL。 | @@ -122,7 +122,7 @@ description: API 网关 Apache APISIX 的 rocketmq-logger 插件用于将日志 | 名称 | 类型 | 必选项 | 默认值 | 描述 | |------------|--------|-----|-------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| log_format | object | 否 | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::note 注意 @@ -149,7 +149,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/rocketmq-logger \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -157,8 +159,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/rocketmq-logger \ 在日志收集处，将得到类似下面的日志： ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## 启用插件 diff --git a/docs/zh/latest/plugins/skywalking-logger.md b/docs/zh/latest/plugins/skywalking-logger.md index 79eab655ed6a..3fcabe6cd7a1 100644 --- a/docs/zh/latest/plugins/skywalking-logger.md +++ b/docs/zh/latest/plugins/skywalking-logger.md @@ -44,7 +44,7 @@ description: skywalking-logger 将请求和响应日志作为 JSON 对象批量 | endpoint_addr | string | 是 | | | SkyWalking OAP 服务器的 URI。 | | service_name | string | 否 |"APISIX" | | SkyWalking 服务名称。 | | service_instance_name | string | 否 |"APISIX Instance Name"| | SkyWalking 服务的实例名称。当设置为 `$hostname` 会直接获取本地主机名。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | timeout | integer | 否 | 3 | [1,...] | 发送请求后保持连接活动的时间。 | | name | string | 否 | "skywalking logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 | | include_req_body | boolean | 否 | false |如果为 true，则将请求主体包含在日志中。请注意，如果请求主体太大而无法保存在内存中，则由于 NGINX 的限制而无法记录。| @@ -60,7 +60,7 @@ description: skywalking-logger 将请求和响应日志作为 JSON 对象批量 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------------- | ------- | ------ | -------------------- | ------------- | ---------------------------------------------------------------- | -| log_format | object | 否 | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | ## 示例 diff --git a/docs/zh/latest/plugins/sls-logger.md b/docs/zh/latest/plugins/sls-logger.md index 12f465386b29..a3374f7ae744 100644 --- a/docs/zh/latest/plugins/sls-logger.md +++ b/docs/zh/latest/plugins/sls-logger.md @@ -37,7 +37,7 @@ title: sls-logger | host | 必要的 | TCP 服务的 IP 地址或主机名，请参考：[阿里云日志服务列表](https://help.aliyun.com/document_detail/29008.html?spm=a2c4g.11186623.2.14.49301b4793uX0z#reference-wgx-pwq-zdb)，建议配置 IP 取代配置域名。| | port | 必要的 | 目标端口，阿里云日志服务默认端口为 10009。| | timeout | 可选的 | 发送数据超时间。| -| log_format | 可选的 | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | 可选的 | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | project | 必要的 | 日志服务 Project 名称，请提前在阿里云日志服务中创建 Project。| | logstore | 必须的 | 日志服务 Logstore 名称，请提前在阿里云日志服务中创建 Logstore。| | access_key_id | 必须的 | AccessKey ID。建议使用阿里云子账号 AK，详情请参见 [授权](https://help.aliyun.com/document_detail/47664.html?spm=a2c4g.11186623.2.15.49301b47lfvxXP#task-xsk-ttc-ry)。| @@ -83,7 +83,7 @@ title: sls-logger | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 可选 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [Nginx 内置变量](http://nginx.org/en/docs/varindex.html)。特别的，**该设置是全局生效的**，意味着指定 log_format 后，将对所有绑定 sls-logger 的 Route 或 Service 生效。 | +| log_format | object | 可选 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [Nginx 内置变量](http://nginx.org/en/docs/varindex.html)。特别的，**该设置是全局生效的**，意味着指定 log_format 后，将对所有绑定 sls-logger 的 Route 或 Service 生效。 | ### 设置日志格式示例 @@ -103,7 +103,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/sls-logger -H "X-API-KEY "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -111,8 +113,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/sls-logger -H "X-API-KEY 在日志收集处，将得到类似下面的日志： ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## 如何开启 diff --git a/docs/zh/latest/plugins/splunk-hec-logging.md b/docs/zh/latest/plugins/splunk-hec-logging.md index ef22594096e1..d50a4fc450b6 100644 --- a/docs/zh/latest/plugins/splunk-hec-logging.md +++ b/docs/zh/latest/plugins/splunk-hec-logging.md @@ -44,7 +44,7 @@ description: API 网关 Apache APISIX 的 splunk-hec-logging 插件可用于将 | endpoint.channel | 否 | | Splunk HEC 发送渠道标识，更多信息请参考 [About HTTP Event Collector Indexer Acknowledgment](https://docs.splunk.com/Documentation/Splunk/8.2.3/Data/AboutHECIDXAck)。 | | endpoint.timeout | 否 | 10 | Splunk HEC 数据提交超时时间（以秒为单位）。 | | ssl_verify | 否 | true | 当设置为 `true` 时，启用 `SSL` 验证。 | -| log_format | 否 | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | 本插件支持使用批处理器来聚合并批量处理条目（日志和数据）。这样可以避免该插件频繁地提交数据。默认情况下每 `5` 秒钟或队列中的数据达到 `1000` 条时，批处理器会自动提交数据，如需了解更多信息或自定义配置，请参考 [Batch-Processor](../batch-processor.md#配置)。 @@ -83,7 +83,7 @@ description: API 网关 Apache APISIX 的 splunk-hec-logging 插件可用于将 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头。则表明获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::info 注意 @@ -110,7 +110,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/splunk-hec-logging \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -118,7 +120,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/splunk-hec-logging \ 配置完成后，你将在日志系统中看到如下类似日志： ```json -[{"time":1673976669.269,"source":"apache-apisix-splunk-hec-logging","event":{"host":"localhost","client_ip":"127.0.0.1","@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1"},"host":"DESKTOP-2022Q8F-wsl","sourcetype":"_json"}] +[{"time":1673976669.269,"source":"apache-apisix-splunk-hec-logging","event":{"host":"localhost","client_ip":"127.0.0.1","@timestamp":"2023-01-09T14:47:25+08:00","request":{"method":"GET","uri":"/splunk.do"},"response":{"status":200},"route_id":"1"},"host":"DESKTOP-2022Q8F-wsl","sourcetype":"_json"}] ``` ## 启用插件 diff --git a/docs/zh/latest/plugins/syslog.md b/docs/zh/latest/plugins/syslog.md index c4a351ee3791..ac2acf334271 100644 --- a/docs/zh/latest/plugins/syslog.md +++ b/docs/zh/latest/plugins/syslog.md @@ -48,7 +48,7 @@ description: API 网关 Apache APISIX syslog 插件可用于将日志推送到 S | max_retry_count | integer | 否 | | [1, ...] | 连接到日志服务器失败或将日志消息发送到日志服务器失败后的最大重试次数。 | | retry_delay | integer | 否 | | [0, ...] | 重试连接到日志服务器或重试向日志服务器发送日志消息之前的时间延迟（以毫秒为单位）。 | | pool_size | integer | 否 | 5 | [5, ...] | `sock：keepalive` 使用的 Keepalive 池大小。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时包括请求体。 | | include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时的过滤器。只有当此处设置的表达式求值为 `true` 时，才会记录请求体。有关更多信息，请参阅 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 。 | | include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 | @@ -66,7 +66,7 @@ description: API 网关 Apache APISIX syslog 插件可用于将日志推送到 S | 名称 | 类型 | 必选项 | 默认值 | 描述 | |------------|--------|-----|-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| log_format | object | 否 | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头。则表明获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::info 重要 diff --git a/docs/zh/latest/plugins/tcp-logger.md b/docs/zh/latest/plugins/tcp-logger.md index 158bb7cba293..2350ff8e1b3c 100644 --- a/docs/zh/latest/plugins/tcp-logger.md +++ b/docs/zh/latest/plugins/tcp-logger.md @@ -40,7 +40,7 @@ description: 本文介绍了 API 网关 Apache APISIX 如何使用 tcp-logger | host | string | 是 | | | TCP 服务器的 IP 地址或主机名。 | | port | integer | 是 | | [0,...] | 目标端口。 | | timeout | integer | 否 | 1000 | [1,...] | 发送数据超时间。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | tls | boolean | 否 | false | | 用于控制是否执行 SSL 验证。 | | tls_options | string | 否 | | | TLS 选项。 | | include_req_body | boolean | 否 | | [false, true] | 当设置为 `true` 时，日志中将包含请求体。 | @@ -94,7 +94,7 @@ description: 本文介绍了 API 网关 Apache APISIX 如何使用 tcp-logger | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头。则表明获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::info 注意 @@ -121,7 +121,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tcp-logger \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -129,7 +131,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tcp-logger \ 配置完成后，你将在日志系统中看到如下类似日志： ```json -{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1"} +{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200}} ``` ## 启用插件 diff --git a/docs/zh/latest/plugins/tencent-cloud-cls.md b/docs/zh/latest/plugins/tencent-cloud-cls.md index a5c41bd72d62..f0fb82a505c3 100644 --- a/docs/zh/latest/plugins/tencent-cloud-cls.md +++ b/docs/zh/latest/plugins/tencent-cloud-cls.md @@ -46,7 +46,7 @@ description: API 网关 Apache APISIX tencent-cloud-cls 插件可用于将日志 | include_resp_body | boolean | 否 | false | [false, true]| 当设置为 `true` 时，日志中将包含响应体。 | | include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 属性设置为 `true` 时进行过滤响应体，并且只有当此处设置的表达式计算结果为 `true` 时，才会记录响应体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 | | global_tag | object | 否 | | | kv 形式的 JSON 数据，可以写入每一条日志，便于在 CLS 中检索。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | 注意：schema 中还定义了 `encrypt_fields = {"secret_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 @@ -96,7 +96,7 @@ description: API 网关 Apache APISIX tencent-cloud-cls 插件可用于将日志 | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头。则表明获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::info 重要 @@ -123,7 +123,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tencent-cloud-cls \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -131,8 +133,8 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tencent-cloud-cls \ 配置完成后，你将在日志系统中看到如下类似日志： ```shell -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} -{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} +{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"} ``` ## 启用插件 diff --git a/docs/zh/latest/plugins/udp-logger.md b/docs/zh/latest/plugins/udp-logger.md index 45d0983ffbde..bb60ea38ddb8 100644 --- a/docs/zh/latest/plugins/udp-logger.md +++ b/docs/zh/latest/plugins/udp-logger.md @@ -40,7 +40,7 @@ description: 本文介绍了 API 网关 Apache APISIX 如何使用 udp-logger | host | string | 是 | | | UDP 服务的 IP 地址或主机名。 | | port | integer | 是 | | [0,...] | 目标端口。 | | timeout | integer | 否 | 1000 | [1,...] | 发送数据超时间。 | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | | name | string | 否 | "udp logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 | | include_req_body | boolean | 否 | | [false, true] | 当设置为 `true` 时，日志中将包含请求体。 | | include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时的过滤器。只有当此处设置的表达式求值为 `true` 时，才会记录请求体。有关更多信息，请参阅 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 。 | @@ -93,7 +93,7 @@ description: 本文介绍了 API 网关 Apache APISIX 如何使用 udp-logger | 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | | ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头。则表明获取 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | :::info 注意 @@ -120,7 +120,9 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/udp-logger \ "log_format": { "host": "$host", "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" + "client_ip": "$remote_addr", + "request": { "method": "$request_method", "uri": "$request_uri" }, + "response": { "status": "$status" } } }' ``` @@ -128,7 +130,7 @@ curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/udp-logger \ 配置完成后，你将在日志系统中看到如下类似日志： ```json -{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1"} +{"@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1","host":"localhost","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200}} ``` ## 如何开启 From 314f749d5fcb4923c89da11362b72b0de7295edf Mon Sep 17 00:00:00 2001 From: tygwak Date: Fri, 7 Nov 2025 13:21:53 +0900 Subject: [PATCH 5/5] docs: fix elasticsearch-logger docs --- docs/en/latest/plugins/elasticsearch-logger.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/en/latest/plugins/elasticsearch-logger.md b/docs/en/latest/plugins/elasticsearch-logger.md index b885fc66d05c..acb46001abc8 100644 --- a/docs/en/latest/plugins/elasticsearch-logger.md +++ b/docs/en/latest/plugins/elasticsearch-logger.md @@ -61,12 +61,8 @@ This Plugin supports using batch processors to aggregate and process entries (lo | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| -<<<<<<< HEAD -| 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 `$`. | -======= -| log_format | object | False | | Custom log format in key-value pairs in JSON format. Support [APISIX variables](../apisix-variable.md) and [NGINX variables](http://nginx.org/en/docs/varindex.html) in values. | +| log_format | object | False | | Log format declared 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](http://nginx.org/en/docs/varindex.html) variables 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. | ->>>>>>> origin/master ## Examples