This is an automated email from the ASF dual-hosted git repository.
xiaoyu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-shenyu-website.git
The following commit(s) were added to refs/heads/main by this push:
new aad07d802c add logging-elasticsearch doc (#623)
aad07d802c is described below
commit aad07d802c9621f6b29a6ecb75663f7fb1463969
Author: qinghai777 <[email protected]>
AuthorDate: Tue Jun 28 00:17:19 2022 +0800
add logging-elasticsearch doc (#623)
* add logging-elasticsearch doc
* modify 01
* modify 02
* modify 03
* modify 04
* modify 05
* modify 05
* modify 06
---
.../observability/logging-elasticsearch.md | 137 +++++++++++++++++++++
.../observability/logging-elasticsearch.md | 136 ++++++++++++++++++++
.../plugin/logging/logging-elasticsearch/data.png | Bin 0 -> 100999 bytes
.../elasticsearch-success.png | Bin 0 -> 8398 bytes
.../plugin/logging/logging-elasticsearch/index.png | Bin 0 -> 36969 bytes
.../logging-elasticsearch/kibana-success.png | Bin 0 -> 7810 bytes
.../logging-elasticsearch-arch.png | Bin 0 -> 128498 bytes
.../logging-elasticsearch-config-cn.png | Bin 0 -> 37131 bytes
.../logging-elasticsearch-config-en.png | Bin 0 -> 32889 bytes
.../logging-elasticsearch-option.png | Bin 0 -> 64720 bytes
.../logging-elasticsearch/postman-request.png | Bin 0 -> 33303 bytes
11 files changed, 273 insertions(+)
diff --git a/docs/plugin-center/observability/logging-elasticsearch.md
b/docs/plugin-center/observability/logging-elasticsearch.md
new file mode 100644
index 0000000000..e854b16b1b
--- /dev/null
+++ b/docs/plugin-center/observability/logging-elasticsearch.md
@@ -0,0 +1,137 @@
+---
+title: Logging-ElasticSearch Plugin
+keywords: ["Logging", "ElasticSearch"]
+description: Logging-ElasticSearch Plugin
+---
+
+## Description
+
+>`Apache ShenYu` The gateway receives requests from the client, forwards them
to the server, and returns the server results to the client. The gateway can
record the details of each request，
+>The list includes: request time, request parameters, request path, response
result, response status code, time consumption, upstream IP, exception
information waiting.
+>Shenyu gateway can record access logs through logging-elasticsearch-plugin
and send access logs to elasticsearch database.
+
+
+## Technical Solutions
+
+* Architecture Diagram
+
+
+
+## Plugin Usage
+
+### 1.Add the dependency of logging-elasticsearch to the
Shenyu-bootstrap-module 's `pom.xml` file.
+
+```xml
+ <!--shenyu logging-elasticsearch plugin start-->
+ <dependency>
+ <groupId>org.apache.shenyu</groupId>
+
<artifactId>shenyu-spring-boot-starter-plugin-logging-elasticsearch</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <!--shenyu logging-elasticsearch plugin end-->
+```
+
+### 2.In `shenyu-admin` --> Basic Configuration --> Plugin Management -->
`loggingElasticSearch`, configure the ElasticSearch parameter and set it to on.
+
+#### 2.1Open the plugin and configure elasticsearch, configure it as follows.
+
+
+
+- The individual configuration items are described as follows:
+
+| config-item | type | description
| remarks |
+| :-------------- | :------ |
:----------------------------------------------------------- |
:---------------------------------- |
+| host | String | host name
| must |
+| prot | String | port num
| must |
+| sampleRate | String | Sampling rate, range 0~1, 0: off, 0.01:
acquisition 1%, 1: acquisition 100% | Optional, default 1, all collection |
+| compressAlg | String | Compression algorithm, no compression by
default, currently supports LZ4 compression | Optional, no compression by
default |
+| maxResponseBody | Ingeter | Maximum response size, above the threshold no
response will be collected | Optional, default 512KB |
+| maxRequestBody | Ingeter | Maximum request body size, above the threshold
no request body will be collected | Optional, default 512KB |
+Except for host, port, all others are optional, in most cases only these 3
items need to be configured.
+
+#### 2.2 Configuring Selectors and Rulers
+
+For detailed configuration of selectors and rules, please refer to: [Selector
and rule management](../../user-guide/admin-usage/selector-and-rule)。
+In addition sometimes a large gateway cluster corresponds to multiple
applications (business), different applications (business) corresponds to
different topics, related to isolation,
+then you can configure different topics (optional) and sampling rate
(optional) by selector, the meaning of the configuration items as shown in the
table above.
+The operation is shown below:
+
+
+
+## Logging information
+
+The fields of the captured access log are as follows.
+
+| Field Name | Meaning
| Description |
Remarks |
+| :-------------------- |
:----------------------------------------------------------: |
:----------------------------------------------------------- | :------ |
+| clientIp | Client IP
| |
|
+| timeLocal | Request time string, format: yyyy-MM-dd
HH:mm:ss.SSS |
| |
+| method | request method (different rpc type is not the same,
http class for: get, post wait, rpc class for the interface name) |
| |
+| requestHeader | Request header (json format)
| |
|
+| responseHeader | Response header (json format)
| |
|
+| queryParams | Request query parameters
| |
|
+| requestBody | Request Body (body of binary type will not be
captured) | |
|
+| requestUri | Request uri
| |
|
+| responseBody | Response body
| |
|
+| responseContentLength | Response body size
| |
|
+| rpcType | rpc type
| |
|
+| status | response status
| |
|
+| upstreamIp | Upstream (program providing the service) IP
| |
|
+| upstreamResponseTime | Time taken by the upstream (program providing the
service) to respond to the request (ms ms) |
| |
+| userAgent | Requested user agent
| |
|
+| host | The requested host
| |
|
+| module | Requested modules
| |
|
+| path | The requested path
| |
|
+| traceId | Requested Link Tracking ID
| Need to access link tracking plugins, such as skywalking,zipkin |
|
+
+## Collect Logging
+
+Users need to deploy the `ElasticSearch` service to collect
+
+### Installing ElasticSearch under Windows Environment
+
+- To [download address](https://www.elastic.co/downloads/elasticsearch) Select
Windows version to download
+- After downloading the installation package, unzip it, enter the `bin`
directory, and double-click to execute `elasticsearch.bat` to start
+- The default startup port is `9200`. Access`http://localhost:9200`, verify
success
+
+
+
+### Installing ElasticSearch in MacOS environment
+
+- To [download address](https://www.elastic.co/downloads/elasticsearch) Select
Windows version to download
+- After downloading the installation package, unzip it, enter the `bin`
directory and execute the startup command on the terminal: `./elasticsearch`
+- The default startup port is `9200`. Access `http://localhost:9200`, verify
success
+
+
+
+### Installing Kibana under Windows Environment
+
+- To [download address](https://www.elastic.co/cn/downloads/kibana) Select
Windows version to download
+- After downloading the installation package, unzip it, enter the `bin`
directory, and double-click to execute `kibana.bat` to start
+- The default startup port is `5601`. Access `http://localhost:5601`, verify
success
+
+
+
+### Installing Kibana in MacOS environment
+
+- To [download address](https://www.elastic.co/cn/downloads/kibana) Select
Windows version to download
+- After downloading the installation package, unzip it, enter the `bin`
directory and execute the startup command on the terminal: `./kibana`
+- The default startup port is `5601`. Access `http://localhost:5601`, verify
success
+
+
+
+### Initiate a request, and the elasticsearch java client collects logs and
stores them in the elasticsearch database
+
+#### Using postman to initiate a request
+
+
+
+#### Querying data using kibaba
+
+
+
+- The first time you use the plug-in, you will automatically create a
`shenyu-access-logging` index
+
+
+
+- Using ES query statement, the requested log information can be queried
diff --git
a/i18n/zh/docusaurus-plugin-content-docs/current/plugin-center/observability/logging-elasticsearch.md
b/i18n/zh/docusaurus-plugin-content-docs/current/plugin-center/observability/logging-elasticsearch.md
new file mode 100644
index 0000000000..5804479c30
--- /dev/null
+++
b/i18n/zh/docusaurus-plugin-content-docs/current/plugin-center/observability/logging-elasticsearch.md
@@ -0,0 +1,136 @@
+---
+title: Logging-ElasticSearch插件
+keywords: ["Logging", "ElasticSearch"]
+description: Logging-ElasticSearch插件
+---
+
+## 说明
+
+>`Apache ShenYu` 网关接收客户端请求，向服务端转发请求，并将服务端结果返回给客户端。网关可以记录下每次请求对应的详细信息，
+> 列如： 请求时间、请求参数、请求路径、响应结果、响应状态码、耗时、上游IP、异常信息等待.
+> ShenYu网关可以通过Logging-ElasticSearch插件记录访问日志并将访问日志发送到ElasticSearch数据库。
+
+## 技术方案
+
+* 架构图
+
+
+
+## 插件使用
+
+### 1.在shenyu-bootstrap模块的 `pom.xml` 文件中添加 `Logging-ElasticSearch`的依赖。
+
+```xml
+ <!--shenyu logging-elasticsearch plugin start-->
+ <dependency>
+ <groupId>org.apache.shenyu</groupId>
+
<artifactId>shenyu-spring-boot-starter-plugin-logging-elasticsearch</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <!--shenyu logging-elasticsearch plugin end-->
+```
+
+### 2.在 `shenyu-admin`--> 基础配置 --> 插件管理-> `loggingElasticSearch`
，配置ElasticSearch参数，并设置为开启。
+
+#### 2.1开插件，并配置elasticsearch,配置如下：
+
+
+
+* 各个配置项说明如下：
+
+| 配置项 | 类型 | 说明 | 备注
|
+| :-------------- | :------ |
:------------------------------------------------- | :-------------------- |
+| config-item | type | description
| remarks |
+| host | String | 主机名
| 必须 |
+| port | String | 端口号
| 必须 |
+| sampleRate | String | 采样率，范围0~1，0：关闭，0.01:采集1%，1：采集100% | 可选，默认1，全部采集 |
+| compressAlg | String | 压缩算法，默认不压缩，目前支持LZ4压缩 | 可选，默认不压缩
|
+| maxResponseBody | Ingeter | 最大响应体大小，超过阈值将不采集响应体 | 可选，默认512KB
|
+| maxRequestBody | Ingeter | 最大请求体大小，超过阈值将不采集请求体 | 可选，默认512KB
|
+*除了host、port其它都是可选*，大部分情况下只需要配置这2项就可以了。
+
+#### 2.2 配置选择器和规则器
+
+选择器和规则详细配置，请参考: [选择器和规则管理](../../user-guide/admin-usage/selector-and-rule)。
+另外有时候一个大网关集群对应多个应用程序（业务），不同应用程序（业务）对应不同的主题，相关隔离，这时候可以按选择器配置不同的主题(可选)和采样率(可选)，配置项的含义如上表所示。
+操作如下图：
+
+
+
+## Logging信息
+
+采集的access log的字段如下：
+
+| 字段名称 | 含义
| 说明 | 备注 |
+| :-------------------- |
:----------------------------------------------------------: |
:---------------------------------------- | :--- |
+| clientIp | 客户端IP
| | |
+| timeLocal | 请求时间字符串, 格式：yyyy-MM-dd HH:mm:ss.SSS |
| |
+| method | 请求方法(不同rpc类型不一样，http类的为:get,post等待，rpc类的为接口名称) |
| |
+| requestHeader | 请求头(json格式)
| | |
+| responseHeader | 响应头(json格式)
| | |
+| queryParams | 请求查询参数
| | |
+| requestBody | 请求Body（二进制类型的body不会采集） |
| |
+| requestUri | 请求uri
| | |
+| responseBody | 响应body
| | |
+| responseContentLength | 响应body大小
| | |
+| rpcType | rpc类型
| | |
+| status | 响应码
| | |
+| upstreamIp | 上游(提供服务的程序)IP
| | |
+| upstreamResponseTime | 上游(提供服务的程序)响应请求的耗时(毫秒ms) |
| |
+| userAgent | 请求的用户代理
| | |
+| host | 请求的host
| | |
+| module | 请求的模块
| | |
+| path | 请求的路径path
| | |
+| traceId | 请求的链路追踪ID
| 需要接入链路追踪插件，如skywalking,zipkin | |
+
+## 收集Logging
+
+用户需要部署`ElasticSearch`服务来采集
+
+### windows 环境下安装ElasticSearch
+
+- 到[下载地址](https://www.elastic.co/downloads/elasticsearch)选择windows版本进行下载
+- 下载安装包后解压，进入`bin`目录下,双击执行`elasticsearch.bat`进行启动
+- 默认启动端口为 `9200`，访问 `http://localhost:9200`，验证是否成功
+
+
+
+### macos 环境下安装ElasticSearch
+
+- 到[下载地址](https://www.elastic.co/downloads/elasticsearch)选择macos版本进行下载
+- 下载安装包后解压，进入`bin`目录下,在终端执行启动命令: `./elasticsearch`
+- 默认启动端口为 `9200`，访问 `http://localhost:9200`，验证是否成功
+
+
+
+### windows 环境下安装Kibana
+
+- 到[下载地址](https://www.elastic.co/cn/downloads/kibana)选择windows版本进行下载
+- 下载安装包后解压，进入`bin`目录下,双击执行`kibana.bat`进行启动
+- 默认启动端口为 `5601`，访问 `http://localhost:5601`，验证是否成功（前提是ElasticSearch已打开）
+
+
+
+### macos 环境下安装Kibana
+
+- 到[下载地址](https://www.elastic.co/cn/downloads/kibana)选择windows版本进行下载
+- 下载安装包后解压，进入`bin`目录下,在终端执行启动命令: `./kibana`
+- 默认启动端口为 `5601`，访问 `http://localhost:5601`，验证是否成功（前提是ElasticSearch已打开）
+
+
+
+### 发起请求，ElasticSearch的Java客户端收集日志并存储进ElasticSearch数据库
+
+#### 使用postman发起请求
+
+
+
+#### 使用Kibaba查询数据
+
+
+
+- 第一次使用插件会自动创建`shenyu-access-logging`索引
+
+
+
+- 利用es查询语句可以查询到请求的日志信息
diff --git a/static/img/shenyu/plugin/logging/logging-elasticsearch/data.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/data.png
new file mode 100644
index 0000000000..d67519a1f3
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/data.png differ
diff --git
a/static/img/shenyu/plugin/logging/logging-elasticsearch/elasticsearch-success.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/elasticsearch-success.png
new file mode 100644
index 0000000000..7ed8a1e372
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/elasticsearch-success.png
differ
diff --git a/static/img/shenyu/plugin/logging/logging-elasticsearch/index.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/index.png
new file mode 100644
index 0000000000..fdfa92cb52
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/index.png differ
diff --git
a/static/img/shenyu/plugin/logging/logging-elasticsearch/kibana-success.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/kibana-success.png
new file mode 100644
index 0000000000..0e795ef893
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/kibana-success.png
differ
diff --git
a/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-arch.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-arch.png
new file mode 100644
index 0000000000..a7dd8f9d4f
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-arch.png
differ
diff --git
a/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-config-cn.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-config-cn.png
new file mode 100644
index 0000000000..1105e59f42
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-config-cn.png
differ
diff --git
a/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-config-en.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-config-en.png
new file mode 100644
index 0000000000..72235593a0
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-config-en.png
differ
diff --git
a/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-option.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-option.png
new file mode 100644
index 0000000000..5f73be3beb
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/logging-elasticsearch-option.png
differ
diff --git
a/static/img/shenyu/plugin/logging/logging-elasticsearch/postman-request.png
b/static/img/shenyu/plugin/logging/logging-elasticsearch/postman-request.png
new file mode 100644
index 0000000000..501745b2a2
Binary files /dev/null and
b/static/img/shenyu/plugin/logging/logging-elasticsearch/postman-request.png
differ
