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 612e3775e docs: update "Loggers" Plugins (#7247)
612e3775e is described below
commit 612e3775ec60111b0af547c3749364726a4bc44e
Author: Navendu Pottekkat <navendupottek...@gmail.com>
AuthorDate: Thu Jun 23 18:50:05 2022 +0530
docs: update "Loggers" Plugins (#7247)
---
docs/en/latest/plugins/clickhouse-logger.md | 122 +++++++++++++++-------------
docs/en/latest/plugins/log-rotate.md | 75 +++++++++--------
docs/en/latest/plugins/syslog.md | 59 +++++++-------
3 files changed, 137 insertions(+), 119 deletions(-)
diff --git a/docs/en/latest/plugins/clickhouse-logger.md
b/docs/en/latest/plugins/clickhouse-logger.md
index 2f3fd1744..505a26cd3 100644
--- a/docs/en/latest/plugins/clickhouse-logger.md
+++ b/docs/en/latest/plugins/clickhouse-logger.md
@@ -1,5 +1,11 @@
---
title: clickhouse-logger
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - ClickHouse Logger
+description: This document contains information about the Apache APISIX
clickhouse-logger Plugin.
---
<!--
@@ -23,69 +29,38 @@ title: clickhouse-logger
## Description
-`clickhouse-logger` is a plugin which push Log data requests to clickhouse.
+The `clickhouse-logger` Plugin is used to push logs to
[ClickHouse](https://clickhouse.com/) database.
## Attributes
-| Name | Type | Requirement | Default | Valid |
Description |
-|-----------------|---------| ------ | ------------- | ------- |
------------------------------------------------ |
-| endpoint_addr | string | required | | | The
`clickhouse` endpoint. |
-| database | string | required | | | The DB
name to store log. |
-| logtable | string | required | | | The table
name. |
-| user | string | required | | |
clickhouse user. |
-| password | string | required | | |
clickhouse password. |
-| timeout | integer | optional | 3 | [1,...] | Time to
keep the connection alive after sending a request. |
-| name | string | optional | "clickhouse logger" | | A
unique identifier to identity the logger. |
-| ssl_verify | boolean | optional | true | [true,false] |
verify ssl. |
+| Name | Type | Required | Default | Valid values |
Description |
+|---------------|---------|----------|---------------------|--------------|----------------------------------------------------------------|
+| endpoint_addr | string | True | | |
ClickHouse endpoint. |
+| database | string | True | | |
Name of the database to store the logs. |
+| logtable | string | True | | |
Table name to store the logs. |
+| user | string | True | | |
ClickHouse username. |
+| password | string | True | | |
ClickHouse password. |
+| 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. |
+| ssl_verify | boolean | False | true | [true,false] |
When set to `true`, verifies SSL. |
-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
-
-The following is an example of how to enable the `clickhouse-logger` for a
specific route.
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "clickhouse-logger": {
- "user": "default",
- "password": "a",
- "database": "default",
- "logtable": "test",
- "endpoint_addr": "http://127.0.0.1:8123";
- }
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
- }
- },
- "uri": "/hello"
-}'
-```
+## Metadata
-## Test Plugin
+You can also set the format of the logs by configuring the Plugin metadata.
The following configurations are available:
-> success:
+| 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 `$`. |
-```shell
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 200 OK
-...
-hello, world
-```
+:::info IMPORTANT
-## 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). |
+Configuring the Plugin metadata is global in scope. This means that it will
take effect on all Routes and Services which use the `clickhouse-logger` Plugin.
- Note that **the metadata configuration is applied in global scope**, which
means it will take effect on all Route or Service which use clickhouse-logger
plugin.
+:::
-### Example
+The example below shows how you can configure through the Admin API:
```shell
curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/clickhouse-logger -H
'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -98,7 +73,7 @@ curl
http://127.0.0.1:9080/apisix/admin/plugin_metadata/clickhouse-logger -H 'X-
}'
```
-create clickhouse log table
+You have to then create a table in your ClickHouse database to store the logs:
```sql
CREATE TABLE default.test (
@@ -110,7 +85,7 @@ CREATE TABLE default.test (
) ENGINE = MergeTree()
```
-On clickhouse run `select * from default.test;`, will got below row:
+Now, if you run `select * from default.test;`, you will get the following row:
```
┌─host──────┬─client_ip─┬─route_id─┬─@timestamp────────────────┐
@@ -118,13 +93,46 @@ On clickhouse run `select * from default.test;`, will got
below row:
└───────────┴───────────┴──────────┴───────────────────────────┘
```
+## Enabling the Plugin
+
+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/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "clickhouse-logger": {
+ "user": "default",
+ "password": "a",
+ "database": "default",
+ "logtable": "test",
+ "endpoint_addr": "http://127.0.0.1:8123";
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "uri": "/hello"
+}'
+```
+
+## Example usage
+
+Now, if you make a request to APISIX, it will be logged in your ClickHouse
database:
+
+```shell
+curl -i http://127.0.0.1:9080/hello
+```
+
## Disable Plugin
-Remove the corresponding json configuration in the plugin configuration to
disable the `clickhouse-logger`.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+To disable the `clickhouse-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 '
{
"uri": "/hello",
"plugins": {},
diff --git a/docs/en/latest/plugins/log-rotate.md
b/docs/en/latest/plugins/log-rotate.md
index fd7adb383..3c4cc7ecc 100644
--- a/docs/en/latest/plugins/log-rotate.md
+++ b/docs/en/latest/plugins/log-rotate.md
@@ -1,5 +1,11 @@
---
title: log-rotate
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - Log rotate
+description: This document contains information about the Apache APISIX
log-rotate Plugin.
---
<!--
@@ -23,24 +29,44 @@ title: log-rotate
## Description
-The plug-in can automatically rotate access and error log files in the log
directory at regular intervals.
+The `log-rotate` Plugin is used to keep rotating access and error log files in
the log directory at regular intervals.
-Specify how often logs are rotated every interval and how many logs have been
kept recently.
-When the number of log files exceeds the remaining number, the old files are
automatically deleted.
+You can configure how often the logs are rotated and how many logs to keep.
When the number of logs exceeds, older logs are automatically deleted.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description
|
-| -------- | ------- | ----------- | ------- | ----- |
--------------------------------------------------------------------------------------------------------------------
|
-| interval | integer | required | 60 * 60 | | How often to rotate the
log in seconds
|
-| max_kept | integer | required | 24 * 7 | | How many historical
logs can be kept at most. When this number is exceeded, old files will be
deleted automatically. |
-| enable_compression | boolean | optional | false | | Whether to
enable log file compression(gzip). This feature requires `tar` installed.
|
+| Name | Type | Required | Default | Description
|
+|--------------------|---------|----------|---------|------------------------------------------------------------------------------------------------|
+| interval | integer | True | 60 * 60 | Time in seconds
specifying how often to rotate the logs. |
+| max_kept | integer | True | 24 * 7 | Maximum number of
historical logs to keep. If this number is exceeded, older logs are deleted. |
+| enable_compression | boolean | False | false | When set to `true`,
compresses the log file (gzip). Requires `tar` to be installed. |
-After this plug-in is enabled, the log file will be automatically rotated
according to the configuration.
-For example, the following example is a sample based on `interval: 10` and
`max_kept: 10`.
+## Enabling the Plugin
+
+To enable the Plugin, add it in your configuration file (`conf/config.yaml`):
+
+```yaml title="conf/config.yaml"
+plugins:
+ - log-rotate
+
+plugin_attr:
+ log-rotate:
+ interval: 3600
+ max_kept: 168
+ enable_compression: false
+```
+
+## Example usage
+
+Once you enable the Plugin as shown above, the logs will be stored and rotated
based on your configuration.
+
+In the example below the `interval` is set to `10` and `max_kept` is set to
`10`. This will create logs as shown:
+
+```shell
+ll logs
+```
```shell
-$ ll logs
total 44K
-rw-r--r--. 1 resty resty 0 Mar 20 20:32 2020-03-20_20-32-40_access.log
-rw-r--r--. 1 resty resty 2.4K Mar 20 20:32 2020-03-20_20-32-40_error.log
@@ -66,10 +92,9 @@ total 44K
-rw-r--r--. 1 resty resty 1.5K Mar 20 21:31 error.log
```
-When enable log file compression, log file will be like below.
+If you have enabled compression, the logs will be as shown below:
```shell
-$ ll logs
total 10.5K
-rw-r--r--. 1 resty resty 1.5K Mar 20 20:33
2020-03-20_20-33-50_access.log.tar.gz
-rw-r--r--. 1 resty resty 1.5K Mar 20 20:33
2020-03-20_20-33-50_error.log.tar.gz
@@ -81,27 +106,11 @@ total 10.5K
-rw-r--r--. 1 resty resty 1.5K Mar 20 21:31 error.log
```
-### Example
+## Disable plugin
-#### Enable plugin
+To remove the `log-rotate` Plugin, you can remove it from your configuration
file (`conf/config.yaml`):
-Enable the plug-in `log-rotate` in `conf/config.yaml`, then this plugin can
work fine.
-It does not need to be bound in any route or service.
-
-Here is an example of `conf/config.yaml`:
-
-```yaml
+```yaml title="conf/config.yaml"
plugins:
- # the plugins you enabled
- - log-rotate
-
-plugin_attr:
- log-rotate:
- interval: 3600 # rotate interval (unit: second)
- max_kept: 168 # max number of log files will be kept
- enable_compression: false # enable log file compression(gzip) or
not, default false
+ # - log-rotate
```
-
-#### Disable plugin
-
-Remove the plugin `log-rotate` from `conf/config.yaml`.
diff --git a/docs/en/latest/plugins/syslog.md b/docs/en/latest/plugins/syslog.md
index 6b5c6ea99..b8e46c78f 100644
--- a/docs/en/latest/plugins/syslog.md
+++ b/docs/en/latest/plugins/syslog.md
@@ -1,7 +1,12 @@
---
title: syslog
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - Syslog
+description: This document contains information about the Apache APISIX syslog
Plugin.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,32 +28,32 @@ title: syslog
## Description
-`sys` is a plugin which push Log data requests to Syslog.
+The `syslog` Plugin is used to push logs to a Syslog server.
-This will provide the ability to send Log data requests as JSON objects.
+Logs can be set as JSON objects.
## Attributes
-| Name | Type | Requirement | Default | Valid |
Description
|
-| ---------------- | ------- | ----------- | ------------ | ------------- |
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
-| host | string | required | | | IP
address or the Hostname.
|
-| port | integer | required | | |
Target upstream port.
|
-| name | string | optional | "sys logger" | |
|
-| timeout | integer | optional | 3000 | [1, ...] |
Timeout for the upstream to send data (unit: ms).
|
-| tls | boolean | optional | false | |
Control whether to perform SSL verification
|
-| flush_limit | integer | optional | 4096 | [1, ...] | If
the buffered messages' size plus the current message size reaches (>=) this
limit (in bytes), the buffered log messages will be written to log server.
Default to 4096 (4KB). |
-| drop_limit | integer | optional | 1048576 | | If
the buffered messages' size plus the current message size is larger than this
limit (in bytes), the current log message will be dropped because of limited
buffer size. Default to 1048576 (1MB). |
-| sock_type | string | optional | "tcp" | ["tcp", "udp] | IP
protocol type to use for transport layer.
|
-| max_retry_times | integer | optional | | [1, ...] |
Deprecated. Use max_retry_count instead. Max number of retry times after a
connect to a log server failed or send log messages to a log server failed.
|
-| retry_interval | integer | optional | | [0, ...] |
Deprecated. Use retry_delay instead. The time delay (in ms) before retry to
connect to a log server or retry to send log messages to a log server
|
-| pool_size | integer | optional | 5 | [5, ...] |
Keepalive pool size used by sock:keepalive.
|
-| 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 Syslog server.
|
+| port | integer | True | | |
Target port of the Syslog server.
|
+| name | string | False | "sys logger" | |
Identifier for the server.
|
+| timeout | integer | False | 3000 | [1, ...] |
Timeout in ms for the upstream to send data.
|
+| tls | boolean | False | false | | When
set to `true` performs TLS verification.
|
+| flush_limit | integer | False | 4096 | [1, ...] |
Maximum size of the buffer (KB) and the current message before it is flushed
and written to the server. |
+| 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.
|
+| max_retry_times | integer | False | | [1, ...] |
Deprecated. Use `max_retry_count` instead. Maximum number of retries if a
connection to a log server fails. |
+| retry_interval | integer | False | | [0, ...] |
Deprecated. Use `retry_delay` instead. Time in ms before retrying the
connection to the log server. |
+| pool_size | integer | False | 5 | [5, ...] |
Keep-alive pool size used by `sock:keepalive`.
|
+| 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 sys-logger for a specific
route.
+The example below shows how you can enable the Plugin for a specific Route:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -70,24 +75,20 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-## Test Plugin
+## Example usage
-* success:
+Now, if you make a request to APISIX, it will be logged in your Syslog 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 `sys-logger`.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
+To disable the `syslog` 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",
