You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/06/23 13:20:45 UTC
[apisix] branch master updated: docs: update "Loggers" Plugins 2/n (#7246)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new cec618104 docs: update "Loggers" Plugins 2/n (#7246)
cec618104 is described below
commit cec618104c86c154a584a9c09b230323c4f8b374
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Thu Jun 23 18:50:38 2022 +0530
docs: update "Loggers" Plugins 2/n (#7246)
---
docs/en/latest/plugins/kafka-logger.md | 258 +++++++++++++++---------------
docs/en/latest/plugins/rocketmq-logger.md | 247 ++++++++++++++--------------
docs/en/latest/plugins/udp-logger.md | 49 +++---
3 files changed, 278 insertions(+), 276 deletions(-)
diff --git a/docs/en/latest/plugins/kafka-logger.md b/docs/en/latest/plugins/kafka-logger.md
index c2f50b9bb..d492857e0 100644
--- a/docs/en/latest/plugins/kafka-logger.md
+++ b/docs/en/latest/plugins/kafka-logger.md
@@ -1,5 +1,11 @@
---
title: kafka-logger
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - Kafka Logger
+description: This document contains information about the Apache APISIX kafka-logger Plugin.
---
<!--
@@ -23,117 +29,135 @@ title: kafka-logger
## Description
-`kafka-logger` is a plugin which works as a Kafka client driver for the ngx_lua nginx module.
+The `kafka-logger` Plugin is used to push logs as JSON objects to Apache Kafka clusters. It works as a Kafka client driver for the ngx_lua Nginx module.
-This plugin provides the ability to push requests log data as JSON objects to your external Kafka clusters. In case if you did not receive the log data don't worry give it some time it will automatically send the logs after the timer function expires in our Batch Processor.
-
-For more info on Batch-Processor in Apache APISIX please refer.
-[Batch-Processor](../batch-processor.md)
+It might take some time to receive the log data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ---------------- | ------- | ----------- | -------------- | ------- | ---------------------------------------------------------------------------------------- |
-| broker_list | object | required | | | An array of Kafka brokers. |
-| kafka_topic | string | required | | | Target topic to push data. |
-| producer_type | string | optional | async | ["async", "sync"] | Producer's mode of sending messages. |
-| required_acks | integer | optional | 1 | [0, 1, -1] | The number of acknowledgments the producer requires the leader to have received before considering a request complete. This controls the durability of records that are sent. Semantics is the same as kafka producer acks(If set `acks=0` then the producer will not wait for any acknowledgment from the server at all. The record will be immediately added to the socket buffer and considered sent. `acks=1` This wil [...]
-| key | string | optional | | | Used for partition allocation of messages. |
-| timeout | integer | optional | 3 | [1,...] | Timeout for the upstream to send data. |
-| name | string | optional | "kafka logger" | | A unique identifier to identity the batch processor. |
-| meta_format | enum | optional | "default" | ["default"，"origin"] | `default`: collect the request information with default JSON way. `origin`: collect the request information with original HTTP request. [example](#examples-of-meta_format)|
-| include_req_body | boolean | optional | false | [false, true] | Whether to include the request body. false: indicates that the requested body is not included; true: indicates that the requested body is included. Note: if the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitation. |
-| include_req_body_expr | array | optional | | | When `include_req_body` is true, control the behavior based on the result of the [lua-resty-expr](https://github.com/api7/lua-resty-expr) expression. If present, only log the request body when the result is true. |
-| include_resp_body| boolean | optional | false | [false, true] | Whether to include the response body. The response body is included if and only if it is `true`. |
-| include_resp_body_expr | array | optional | | | When `include_resp_body` is true, control the behavior based on the result of the [lua-resty-expr](https://github.com/api7/lua-resty-expr) expression. If present, only log the response body when the result is true. |
-| cluster_name | integer | optional | 1 | [0,...] | the name of the cluster. When there are two or more kafka clusters, you can specify different names. And this only works with async producer_type.|
-| producer_batch_num | integer | optional | 200 | [1,...] | `batch_num` param in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka), merge message and batch send to server, unit is message count |
-| producer_batch_size | integer | optional | 1048576 | [0,...] | `batch_size` param in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka), unit is byte |
-| producer_max_buffering | integer | optional | 50000 | [1,...] | `max_buffering` param in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka), max buffer size, unit is message count |
-| producer_time_linger | integer | optional | 1 | [1,...] | `flush_time` param in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka), unit is second |
-
-The plugin supports the use of batch processors to aggregate and process entries(logs/data) in a batch. This avoids frequent data submissions by the plugin, which by default the batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. For information or custom batch processor parameter settings, see [Batch-Processor](../batch-processor.md#configuration) configuration section.
-
-### examples of meta_format
-
-- **default**:
-
- ```json
- {
- "upstream": "127.0.0.1:1980",
- "start_time": 1619414294760,
- "client_ip": "127.0.0.1",
- "service_id": "",
- "route_id": "1",
- "request": {
- "querystring": {
- "ab": "cd"
- },
- "size": 90,
- "uri": "/hello?ab=cd",
- "url": "http://localhost:1984/hello?ab=cd",
- "headers": {
- "host": "localhost",
- "content-length": "6",
- "connection": "close"
- },
- "body": "abcdef",
- "method": "GET"
- },
- "response": {
- "headers": {
- "connection": "close",
- "content-type": "text/plain; charset=utf-8",
- "date": "Mon, 26 Apr 2021 05:18:14 GMT",
- "server": "APISIX/2.5",
- "transfer-encoding": "chunked"
- },
- "size": 190,
- "status": 200
- },
- "server": {
- "hostname": "localhost",
- "version": "2.5"
- },
- "latency": 0
- }
- ```
+| Name | Type | Required | Default | Valid values | Description |
+| ---------------------- | ------- | -------- | -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| broker_list | object | True | | | List of Kafka brokers (nodes). |
+| kafka_topic | string | True | | | Target topic to push the logs for organisation. |
+| producer_type | string | False | async | ["async", "sync"] | Message sending mode of the producer. |
+| required_acks | integer | False | 1 | [0, 1, -1] | Number of acknowledgements the leader needs to receive for the producer to consider the request complete. This controls the durability of the sent records. The attribute follows the same configuration as the Kafka `acks` attribute. See [Apache Kafka documentation](https://kafka.apache.org/documentation/#producerconfigs_acks) for more. |
+| key | string | False | | | Key used for allocating partitions for messages. |
+| timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. |
+| name | string | False | "kafka logger" | | Unique identifier for the batch processor. |
+| 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. |
+| 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. |
+| include_resp_body_expr | array | False | | | 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. |
+| cluster_name | integer | False | 1 | [0,...] | Name of the cluster. Used when there are two or more Kafka clusters. Only works if the `producer_type` attribute is set to `async`. |
+| producer_batch_num | integer | optional | 200 | [1,...] | `batch_num` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka). The merge message and batch is send to the server. Unit is message count. [...]
+| producer_batch_size | integer | optional | 1048576 | [0,...] | `batch_size` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) in bytes. [...]
+| producer_max_buffering | integer | optional | 50000 | [1,...] | `max_buffering` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) representing maximum buffer size. Unit is message count. [...]
+| producer_time_linger | integer | optional | 1 | [1,...] | `flush_time` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) in seconds. [...]
+
+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.
+
+:::info IMPORTANT
+
+The data is first written to a buffer. When the buffer exceeds the `batch_max_size` or `buffer_duration` attribute, the data is sent to the Kafka server and the buffer is flushed.
+
+If the process is successful, it will return `true` and if it fails, returns `nil` with a string with the "buffer overflow" error.
+
+:::
+
+### meta_format example
+
+- `default`:
+
+ ```json
+ {
+ "upstream": "127.0.0.1:1980",
+ "start_time": 1619414294760,
+ "client_ip": "127.0.0.1",
+ "service_id": "",
+ "route_id": "1",
+ "request": {
+ "querystring": {
+ "ab": "cd"
+ },
+ "size": 90,
+ "uri": "/hello?ab=cd",
+ "url": "http://localhost:1984/hello?ab=cd",
+ "headers": {
+ "host": "localhost",
+ "content-length": "6",
+ "connection": "close"
+ },
+ "body": "abcdef",
+ "method": "GET"
+ },
+ "response": {
+ "headers": {
+ "connection": "close",
+ "content-type": "text/plain; charset=utf-8",
+ "date": "Mon, 26 Apr 2021 05:18:14 GMT",
+ "server": "APISIX/2.5",
+ "transfer-encoding": "chunked"
+ },
+ "size": 190,
+ "status": 200
+ },
+ "server": {
+ "hostname": "localhost",
+ "version": "2.5"
+ },
+ "latency": 0
+ }
+ ```
-- **origin**:
+- `origin`:
- ```http
- GET /hello?ab=cd HTTP/1.1
- host: localhost
- content-length: 6
- connection: close
+ ```http
+ GET /hello?ab=cd HTTP/1.1
+ host: localhost
+ content-length: 6
+ connection: close
- abcdef
- ```
+ abcdef
+ ```
-## Info
+## Metadata
-The `message` will write to the buffer first.
-It will send to the kafka server when the buffer exceed the `batch_max_size`,
-or every `buffer_duration` flush the buffer.
+You can also set the format of the logs by configuring the Plugin metadata. The following configurations are available:
-In case of success, returns `true`.
-In case of errors, returns `nil` with a string describing the error (`buffer overflow`).
+| Name | Type | Required | Default | Description |
+| ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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 `$`. |
-### Sample broker list
+:::info IMPORTANT
-This plugin supports to push in to more than one broker at a time. Specify the brokers of the external kafka servers as below
-sample to take effect of this functionality.
+Configuring the Plugin metadata is global in scope. This means that it will take effect on all Routes and Services which use the `kafka-logger` Plugin.
-```json
+:::
+
+The example below shows how you can configure through the Admin API:
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/kafka-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
- "127.0.0.1":9092,
- "127.0.0.1":9093
-}
+ "log_format": {
+ "host": "$host",
+ "@timestamp": "$time_iso8601",
+ "client_ip": "$remote_addr"
+ }
+}'
+```
+
+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"}
```
-## How To Enable
+## Enabling the Plugin
-The following is an example on how to enable the kafka-logger for a specific route.
+The example below shows how you can enable the `kafka-logger` Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -160,52 +184,30 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
-
-success:
+This Plugin also supports pushing to more than one broker at a time. You can specify multiple brokers in the Plugin configuration as shown below:
-```shell
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 200 OK
-...
-hello, world
+```json
+"broker_list" :
+ {
+ "127.0.0.1":9092,
+ "127.0.0.1":9093
+ },
```
-## Metadata
-
-| Name | Type | Requirement | Default | Valid | Description |
-| ---------------- | ------- | ----------- | ------------- | ------- | ---------------------------------------------------------------------------------------- |
-| log_format | object | optional | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | | Log format declared as key value pair in JSON format. Only string is supported in the `value` part. If the value starts with `$`, it means to get [APISIX variable](../apisix-variable.md) or [Nginx variable](http://nginx.org/en/docs/varindex.html). |
+## Example usage
- Note that **the metadata configuration is applied in global scope**, which means it will take effect on all Route or Service which use kafka-logger plugin.
-
-### Example
+Now, if you make a request to APISIX, it will be logged in your Kafka server:
```shell
-curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/kafka-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "log_format": {
- "host": "$host",
- "@timestamp": "$time_iso8601",
- "client_ip": "$remote_addr"
- }
-}'
-```
-
-It is expected to see some logs like that:
-
-```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"}
+curl -i http://127.0.0.1:9080/hello
```
## Disable Plugin
-Remove the corresponding json configuration in the plugin configuration to disable the `kafka-logger`.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+To disable the `kafka-logger` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
diff --git a/docs/en/latest/plugins/rocketmq-logger.md b/docs/en/latest/plugins/rocketmq-logger.md
index 60137bc6a..f08397001 100644
--- a/docs/en/latest/plugins/rocketmq-logger.md
+++ b/docs/en/latest/plugins/rocketmq-logger.md
@@ -1,7 +1,12 @@
---
title: rocketmq-logger
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - RocketMQ Logger
+description: This document contains information about the Apache APISIX rocketmq-logger Plugin.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,113 +28,132 @@ title: rocketmq-logger
## Description
-`rocketmq-logger` is a plugin which provides the ability to push requests log data as JSON objects to your external rocketmq clusters.
-
- In case if you did not receive the log data don't worry give it some time it will automatically send the logs after the timer function expires in our Batch Processor.
+The `rocketmq-logger` Plugin provides the ability to push logs as JSON objects to your RocketMQ clusters.
-For more info on Batch-Processor in Apache APISIX please refer.
-[Batch-Processor](../batch-processor.md)
+It might take some time to receive the log data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ---------------- | ------- | ----------- | -------------- | ------- | ---------------------------------------------------------------------------------------- |
-| nameserver_list | object | required | | | An array of rocketmq nameservers. |
-| topic | string | required | | | Target topic to push data. |
-| key | string | optional | | | Keys of messages to send. |
-| tag | string | optional | | | Tags of messages to send. |
-| timeout | integer | optional | 3 | [1,...] | Timeout for the upstream to send data. |
-| use_tls | boolean | optional | false | | Whether to open TLS |
-| access_key | string | optional | "" | | access key for ACL, empty string means disable ACL. |
-| secret_key | string | optional | "" | | secret key for ACL. |
-| name | string | optional | "rocketmq logger" | | A unique identifier to identity the batch processor. |
-| meta_format | enum | optional | "default" | ["default"，"origin"] | `default`: collect the request information with default JSON way. `origin`: collect the request information with original HTTP request. [example](#examples-of-meta_format)|
-| include_req_body | boolean | optional | false | [false, true] | Whether to include the request body. false: indicates that the requested body is not included; true: indicates that the requested body is included. Note: if the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitation. |
-| include_req_body_expr | array | optional | | | When `include_req_body` is true, control the behavior based on the result of the [lua-resty-expr](https://github.com/api7/lua-resty-expr) expression. If present, only log the request body when the result is true. |
-| include_resp_body| boolean | optional | false | [false, true] | Whether to include the response body. The response body is included if and only if it is `true`. |
-| include_resp_body_expr | array | optional | | | When `include_resp_body` is true, control the behavior based on the result of the [lua-resty-expr](https://github.com/api7/lua-resty-expr) expression. If present, only log the response body when the result is true. |
-
-The plugin supports the use of batch processors to aggregate and process entries(logs/data) in a batch. This avoids frequent data submissions by the plugin, which by default the batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. For information or custom batch processor parameter settings, see [Batch-Processor](../batch-processor.md#configuration) configuration section.
-
-### examples of meta_format
-
-- **default**:
-
-```json
- {
- "upstream": "127.0.0.1:1980",
- "start_time": 1619414294760,
- "client_ip": "127.0.0.1",
- "service_id": "",
- "route_id": "1",
- "request": {
- "querystring": {
- "ab": "cd"
+| Name | Type | Required | Default | Valid values | Description |
+|------------------------|---------|----------|-------------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| nameserver_list | object | True | | | List of RocketMQ nameservers. |
+| topic | string | True | | | Target topic to push the data to. |
+| key | string | False | | | Key of the messages. |
+| tag | string | False | | | Tag of the messages. |
+| 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. |
+| secret_key | string | False | "" | | secret key for ACL. |
+| name | string | False | "rocketmq logger" | | Unique identifier for the batch processor. |
+| 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. |
+| 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. |
+| include_resp_body_expr | array | False | | | 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. |
+
+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.
+
+:::info IMPORTANT
+
+The data is first written to a buffer. When the buffer exceeds the `batch_max_size` or `buffer_duration` attribute, the data is sent to the RocketMQ server and the buffer is flushed.
+
+If the process is successful, it will return `true` and if it fails, returns `nil` with a string with the "buffer overflow" error.
+
+:::
+
+### meta_format example
+
+- `default`:
+
+ ```json
+ {
+ "upstream": "127.0.0.1:1980",
+ "start_time": 1619414294760,
+ "client_ip": "127.0.0.1",
+ "service_id": "",
+ "route_id": "1",
+ "request": {
+ "querystring": {
+ "ab": "cd"
+ },
+ "size": 90,
+ "uri": "/hello?ab=cd",
+ "url": "http://localhost:1984/hello?ab=cd",
+ "headers": {
+ "host": "localhost",
+ "content-length": "6",
+ "connection": "close"
+ },
+ "body": "abcdef",
+ "method": "GET"
},
- "size": 90,
- "uri": "/hello?ab=cd",
- "url": "http://localhost:1984/hello?ab=cd",
- "headers": {
- "host": "localhost",
- "content-length": "6",
- "connection": "close"
+ "response": {
+ "headers": {
+ "connection": "close",
+ "content-type": "text/plain; charset=utf-8",
+ "date": "Mon, 26 Apr 2021 05:18:14 GMT",
+ "server": "APISIX/2.5",
+ "transfer-encoding": "chunked"
+ },
+ "size": 190,
+ "status": 200
},
- "body": "abcdef",
- "method": "GET"
- },
- "response": {
- "headers": {
- "connection": "close",
- "content-type": "text/plain; charset=utf-8",
- "date": "Mon, 26 Apr 2021 05:18:14 GMT",
- "server": "APISIX/2.5",
- "transfer-encoding": "chunked"
+ "server": {
+ "hostname": "localhost",
+ "version": "2.5"
},
- "size": 190,
- "status": 200
- },
- "server": {
- "hostname": "localhost",
- "version": "2.5"
- },
- "latency": 0
- }
-```
+ "latency": 0
+ }
+ ```
-- **origin**:
+- `origin`:
-```http
- GET /hello?ab=cd HTTP/1.1
- host: localhost
- content-length: 6
- connection: close
+ ```http
+ GET /hello?ab=cd HTTP/1.1
+ host: localhost
+ content-length: 6
+ connection: close
- abcdef
-```
+ abcdef
+ ```
-## Info
+## Metadata
-The `message` will write to the buffer first.
-It will send to the rocketmq server when the buffer exceed the `batch_max_size`,
-or every `buffer_duration` flush the buffer.
+You can also set the format of the logs by configuring the Plugin metadata. The following configurations are available:
-In case of success, returns `true`.
-In case of errors, returns `nil` with a string describing the error (`buffer overflow`).
+| Name | Type | Required | Default | Description |
+| ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 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 `$`. |
-### Sample Nameserver list
+:::info IMPORTANT
-Specify the nameservers of the external rocketmq servers as below sample.
+Configuring the Plugin metadata is global in scope. This means that it will take effect on all Routes and Services which use the `rocketmq-logger` Plugin.
-```json
-[
- "127.0.0.1:9876",
- "127.0.0.2:9876"
-]
+:::
+
+The example below shows how you can configure through the Admin API:
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/rocketmq-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "log_format": {
+ "host": "$host",
+ "@timestamp": "$time_iso8601",
+ "client_ip": "$remote_addr"
+ }
+}'
+```
+
+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"}
```
-## How To Enable
+## Enabling the Plugin
-The following is an example on how to enable the rocketmq-logger for a specific route.
+The example below shows how you can enable the `rocketmq-logger` Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -152,52 +176,29 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
-
-success:
+This Plugin also supports pushing to more than one nameserver at a time. You can specify multiple nameserver in the Plugin configuration as shown below:
-```shell
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 200 OK
-...
-hello, world
+```json
+"nameserver_list" : [
+ "127.0.0.1:9876",
+ "127.0.0.2:9876"
+]
```
-## Metadata
-
-| Name | Type | Requirement | Default | Valid | Description |
-| ---------------- | ------- | ----------- | ------------- | ------- | ---------------------------------------------------------------------------------------- |
-| log_format | object | optional | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | | Log format declared as key value pair in JSON format. Only string is supported in the `value` part. If the value starts with `$`, it means to get [APISIX variables](../apisix-variable.md) or [Nginx variable](http://nginx.org/en/docs/varindex.html). |
-
- Note that **the metadata configuration is applied in global scope**, which means it will take effect on all Route or Service which use rocketmq-logger plugin.
-
-### Example
+## Example usage
-```shell
-curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/rocketmq-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "log_format": {
- "host": "$host",
- "@timestamp": "$time_iso8601",
- "client_ip": "$remote_addr"
- }
-}'
-```
-
-It is expected to see some logs like that:
+Now, if you make a request to APISIX, it will be logged in your RocketMQ server:
```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"}
+curl -i http://127.0.0.1:9080/hello
```
## Disable Plugin
-Remove the corresponding json configuration in the plugin configuration to disable the `rocketmq-logger`.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+To disable the `rocketmq-logger` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",
diff --git a/docs/en/latest/plugins/udp-logger.md b/docs/en/latest/plugins/udp-logger.md
index 8e6b09a7e..b94231f17 100644
--- a/docs/en/latest/plugins/udp-logger.md
+++ b/docs/en/latest/plugins/udp-logger.md
@@ -1,5 +1,11 @@
---
title: udp-logger
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - UDP Logger
+description: This document contains information about the Apache APISIX udp-logger Plugin.
---
<!--
@@ -23,30 +29,27 @@ title: udp-logger
## Description
-`udp-logger` is a plugin which push Log data requests to UDP servers.
+The `udp-logger` Plugin can be used to push log data requests to UDP servers.
-This will provide the ability to send Log data requests as JSON objects to Monitoring tools and other UDP servers.
+This provides the ability to send log data requests as JSON objects to monitoring tools and other UDP servers.
-This plugin provides the ability to push Log data as a batch to you're external UDP servers. In case if you did not receive the log data don't worry give it some time it will automatically send the logs after the timer function expires in our Batch Processor.
-
-For more info on Batch-Processor in Apache APISIX please refer.
-[Batch-Processor](../batch-processor.md)
+This plugin also allows to push logs as a batch to your external UDP server. It might take some time to receive the log data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ---------------- | ------- | ----------- | ------------ | ------- | ---------------------------------------------------------------------------------------- |
-| host | string | required | | | IP address or the Hostname of the UDP server. |
-| port | integer | required | | [0,...] | Target upstream port. |
-| timeout | integer | optional | 3 | [1,...] | Timeout for the upstream to send data. |
-| name | string | optional | "udp logger" | | A unique identifier to identity the batch processor |
-| include_req_body | boolean | optional | false | | Whether to include the request body |
+| Name | Type | Required | Default | Valid values | Description |
+|------------------|---------|----------|--------------|--------------|----------------------------------------------------------|
+| 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. |
+| name | string | False | "udp logger" | | Unique identifier for the batch processor. |
+| include_req_body | boolean | False | false | | When set to `true` includes the request body in the log. |
-The plugin supports the use of batch processors to aggregate and process entries(logs/data) in a batch. This avoids frequent data submissions by the plugin, which by default the batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. For information or custom batch processor parameter settings, see [Batch-Processor](../batch-processor.md#configuration) configuration section.
+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.
-## How To Enable
+## Enabling the Plugin
-The following is an example on how to enable the udp-logger for a specific route.
+The example below shows how you can enable the Plugin on a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -69,24 +72,20 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
+## Example usage
-* success:
+Now, if you make a request to APISIX, it will be logged in your UDP server:
```shell
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 200 OK
-...
-hello, world
+curl -i http://127.0.0.1:9080/hello
```
## Disable Plugin
-Remove the corresponding json configuration in the plugin configuration to disable the `udp-logger`.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+To disable the `udp-logger` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",