[doc]update doc for custom plugin (#2245)

Signed-off-by: liutianyou <[email protected]>
Co-authored-by: Logic <[email protected]>

home/docs/help/plugin.md

@@ -1,31 +1,103 @@
 ---
-id: plugin  
-title: Custom plugin      
+id: plugin
+title: Custom plugin
 sidebar_label: Custom plugin
 ---
 
-## Custom plugins
-
 ### Introduction
 
-Currently, `Hertzbeat` relies on the `alert` module to notify the user, and then the user can take actions such as sending requests, executing `sql`, executing `shell` scripts, etc. However, this can only be automated manually or by `webhook` to receive the alert message.
-However, at present, it is only possible to automate the process by receiving alert messages manually or through a `webhook`. For this reason, `HertzBeat` has added a new `plugin` module, which has a generic interface `Plugin`, which allows users to implement the `alert` method of this interface and receive the `Alert` class as a parameter to customize the operation.
-After adding the customized code, you only need to package the `plugin` module, copy it to the `/ext-lib` folder under the installation directory, restart the `HertzBeat` main program, and then you can execute the customized function after the alert, without having to re-package and deploy the whole program by yourself.
-Currently, `HertzBeat` only set up the trigger `alert` method after alarm, if you need to set up the trigger method at the time of acquisition, startup program, etc., please mention `Task` in `https://github.com/apache/hertzbeat/issues/new/choose`.
+In the current usage of `HertzBeat`, interaction with external systems only occurs after an alert through the notification feature. The plugin functionality allows users to add custom operations at various stages of the `HertzBeat` lifecycle, such as executing `SQL` or `shell` scripts after an alert, or sending collected monitoring data to other systems. Users can develop plugins following the custom plugin development process, package them, and then upload and enable them using the `Plugin Management` - `Upload Plugin` feature, thereby adding custom functionality without restarting `HertzBeat`.
+
+### Supported Plugin Types
+
+1. `Post-Alert` Plugin
+    - Purpose: Execute custom operations after an alert
+    - Implementing Interface: `org.apache.hertzbeat.plugin.PostAlertPlugin`
+2. `Post-Collect` Plugin
+    - Purpose: Execute custom operations after data collection
+    - Implementing Interface: `org.apache.hertzbeat.plugin.PostCollectPlugin`
+
+If you want to set trigger methods during collection, program startup, etc., please submit a `Task` at `https://github.com/apache/hertzbeat/issues/new/choose`.
 
-### Specific uses
+### Development Steps (Example: Implementing a Post-Alert Plugin)
 
-1. Pull the master branch code `git clone https://github.com/apache/hertzbeat.git` and locate the `plugin` module's
-   `Plugin` interface.
+1. Clone the main branch code `git clone https://github.com/apache/hertzbeat.git`, and locate the `Plugin` interface in the `plugin` module.
    ![plugin-1.png](/img/docs/help/plugin-1.png)
-2. In the `org.apache.hertzbeat.plugin.impl` directory, create a new interface implementation class, such as `org.apache.hertzbeat.plugin.impl.DemoPluginImpl`, and receive the `Alert` class as a parameter, implement the `alert` method, the logic is customized by the user, here we simply print the object.
-   ![plugin-2.png](/img/docs/help/plugin-2.png)
-3. Add the fully qualified names of the interface implementation classes to the `META-INF/services/org.apache.hertzbeat.plugin.Plugin` file, with each implementation class name on a separate line.
+2. In the `org.apache.hertzbeat.plugin.impl` directory (create it if it does not exist), create an implementation class of `org.apache.hertzbeat.plugin.PostAlertPlugin`, such as `org.apache.hertzbeat.plugin.impl.DemoPlugin`. In the implementation class, receive the `Alert` class as a parameter, implement the `execute` method, and define custom logic. Here, we simply print the object.
+
+   ```java
+     package org.apache.hertzbeat.plugin.impl;
+
+     import org.apache.hertzbeat.common.entity.alerter.Alert;
+     import org.apache.hertzbeat.common.entity.plugin.PluginContext;
+     import org.apache.hertzbeat.plugin.PostAlertPlugin;
+     import org.slf4j.Logger;
+     import org.slf4j.LoggerFactory;
+
+     public class DemoPlugin implements PostAlertPlugin {
+
+         private static final Logger log = LoggerFactory.getLogger(DemoPlugin.class);
+
+         @Override
+         public void execute(Alert alert, PluginContext pluginContext) {
+             log.info("DemoPlugin alert: {}", alert);
+             log.info("DemoPlugin pluginContext: {}", pluginContext);
+         }
+     }
+   ```
+
+3. Add the fully qualified name of the implementation class to the `META-INF/services/org.apache.hertzbeat.plugin.PostAlertPlugin` file (create it if it does not exist). Each fully qualified name should be on a separate line.
+
+   ```shell
+   org.apache.hertzbeat.plugin.impl.DemoPluginImpl
+   ```
+
 4. Package the `hertzbeat-plugin` module.
 
-   ![plugin-3.png](/img/docs/help/plugin-3.png)
+   ```shell
+   cd plugin
+   mvn package
+   ```
+
+5. Use the `Plugin Management` - `Upload Plugin` feature to upload the plugin package ending with `-jar-with-lib.jar`, and enable the plugin to execute custom operations after an alert.
+
+### Defining Plugin Parameters
+
+The plugin feature supports custom parameters, and you can fill in the required parameters for the plugin during runtime using the `Plugin Management` - `Edit Parameters` feature.
+Below is an example of defining a plugin with two parameters, detailing the process of defining plugin parameters:
+
+1. Add a parameter definition file in the `define` directory. Note that the parameter definition file must be a YAML file starting with `define`, such as `define-demo.yml`.
+2. Define parameters in `define-demo.yml` as shown below:
+
+    ```yaml
+   params:
+     - field: host
+       # name-param field display i18n name
+       name:
+         zh-CN: 目标 Host
+         en-US: Target Host
+       # type-param field type(most mapping the html input type)
+       type: text
+       # required-true or false
+       required: true
+     # field-param field key
+     - field: port
+       # name-param field display i18n name
+       name:
+         zh-CN: 端口
+         en-US: Port
+       # type-param field type(most mapping the html input type)
+       type: number
+       # when type is number, range is required
+       range: '[0,65535]'
+    ```
 
-5. Copy the packaged `jar` package to the `ext-lib` directory under the installation directory (for `docker` installations, mount the `ext-lib` directory first, then copy it there).
-   ![plugin-4.png](/img/docs/help/plugin-4.png)
+3. Use the parameters in the plugin logic
 
-6. Then restart `HertzBeat` to enable the customized post-alert handling policy.
+   ```java
+    @Override
+    public void execute(Alert alert, PluginContext pluginContext) {
+        log.info("param host:{}",pluginContext.getString("host"));
+        log.info("param port:{}",pluginContext.getInteger("port"));
+    }
+   ```

home/i18n/zh-cn/docusaurus-plugin-content-docs/current/help/plugin.md

@@ -1,31 +1,107 @@
 ---
-id: plugin  
-title: 自定义插件      
-sidebar_label: 自定义插件
+id: plugin
+title: 自定义插件
+sidebar_label: 自定义插件 
 ---
 
-## 自定义插件
-
 ### 简介
 
-当前`Hertzbeat`在使用时，主要依赖`alert`模块对用户进行通知，然后用户采取一些措施如发送请求、执行`sql`、执行`shell`脚本等。
-但目前只能通过手动或者`webhook`接收告警信息进行自动化处理。基于此，`HertzBeat`新增了`plugin`模块，该模块有一个通用接口`Plugin`，用户可以自己实现这个接口的`alert`方法，接收`Alert`类作为参数进行自定义操作。
-用户添加自定义代码后，只需要对`plugin`模块进行打包，拷贝到安装目录下`/ext-lib`文件夹中，重启`HertzBeat`主程序，即可实现告警后执行自定义功能，无需自己重新打包部署整个程序。
-目前，`HertzBeat`只在告警后设置了触发`alert`方法，如需在采集、启动程序等时机设置触发方法，请在`https://github.com/apache/hertzbeat/issues/new/choose` 提`Task`。
+当前`HertzBeat`在使用中，只有在告警后通过通知功能与外部系统产生交互，插件功能支持让用户在 `HertzBeat` 生命周期的各个阶段增加自定义操作。如在告警后执行`sql`、`shell`脚本等操作，在采集到监控数据后发送到其他的系统等。
+用户按照自定义插件的流程开发插件并打包后，将打包后的文件通过 `插件管理` - `上传插件` 功能，上传并启用插件即可在不重启`HertzBeat`的情况下增加自定义功能。
+
+### 支持的插件类型
+
+1. `Post-Alert`插件
+    - 作用：在告警后执行自定义操作
+    - 实现接口：`org.apache.hertzbeat.plugin.PostAlertPlugin`
+2. `Post-Collect`插件
+    - 作用：在采集后执行自定义操作
+    - 实现接口：`org.apache.hertzbeat.plugin.PostCollectPlugin`
+
+如需在采集、启动程序等时机设置触发方法，请在`https://github.com/apache/hertzbeat/issues/new/choose` 提`Task`
 
-### 具体使用
+### 开发步骤 （以实现一个告警后插件为例）
 
 1. 拉取主分支代码 `git clone https://github.com/apache/hertzbeat.git` ，定位到`plugin`模块的
    `Plugin`接口。
    ![plugin-1.png](/img/docs/help/plugin-1.png)
-2. 在`org.apache.hertzbeat.plugin.impl`目录下, 新建一个接口实现类，如`org.apache.hertzbeat.plugin.impl.DemoPluginImpl`,在实现类中接收`Alert`类作为参数，实现`alert`方法，逻辑由用户自定义，这里我们简单打印一下对象。
-   ![plugin-2.png](/img/docs/help/plugin-2.png)
-3. 在 `META-INF/services/org.apache.hertzbeat.plugin.Plugin` 文件中增加接口实现类的全限定名，每个实现类全限定名单独成行。
-4. 打包`hertzbeat-plugin`模块。
+2. 在`org.apache.hertzbeat.plugin.impl`目录下（如果没有请自行创建）, 新建一个 `org.apache.hertzbeat.plugin.PostAlertPlugin` 实现类，如`org.apache.hertzbeat.plugin.impl.DemoPlugin`,在实现类中接收`Alert`
+   类作为参数，实现`execute`方法，逻辑由用户自定义，这里我们简单打印一下对象。
+
+   ```java
+     package org.apache.hertzbeat.plugin.impl;
+
+     import org.apache.hertzbeat.common.entity.alerter.Alert;
+     import org.apache.hertzbeat.common.entity.plugin.PluginContext;
+     import org.apache.hertzbeat.plugin.PostAlertPlugin;
+     import org.slf4j.Logger;
+     import org.slf4j.LoggerFactory;
+
+
+     public class DemoPlugin implements PostAlertPlugin {
+
+         private static final Logger log = LoggerFactory.getLogger(DemoPlugin.class);
+
+         @Override
+         public void execute(Alert alert, PluginContext pluginContext) {
+             log.info("DemoPlugin alert: {}", alert);
+             log.info("DemoPlugin pluginContext: {}", pluginContext);
+         }
+     }
+   ```
+
+3. 在 `META-INF/services/org.apache.hertzbeat.plugin.PostAlertPlugin` （如果没有请自行创建） 文件中增加接口实现类的全限定名，每个实现类全限定名单独成行。
+
+   ```shell
+   org.apache.hertzbeat.plugin.impl.DemoPluginImpl
+   ```
+
+4. 打包 `hertzbeat-plugin` 模块。
+
+   ```shell
+   cd plugin
+   mvn package
+   ```
+
+5. 通过 `插件管理`-`上传插件` 功能，上传以 `-jar-with-lib.jar` 结尾的插件包，启用插件即可在告警后执行自定义操作。
+
+### 定义插件参数
+
+插件功能支持自定义参数，并且在使用插件时可以通过`插件管理` - `编辑参数` 功能填写插件运行时需要的参数。
+下面以定义一个包含两个参数的插件为例，详细介绍定义插件参数的流程：
+
+1. 在 `define` 目录下增加参数定义文件 ，注意参数定义文件必须是名称为 define 开头的 yml 文件，例如 `define-demo.yml`;
+2. 在 `define-demo.yml` 中定义参数，如下所示：
 
-   ![plugin-3.png](/img/docs/help/plugin-3.png)
+    ```yaml
+   params:
+     - field: host
+       # name-param field display i18n name
+       name:
+         zh-CN: 目标 Host
+         en-US: Target Host
+       # type-param field type(most mapping the html input type)
+       type: text
+       # required-true or false
+       required: true
+     # field-param field key
+     - field: port
+       # name-param field display i18n name
+       name:
+         zh-CN: 端口
+         en-US: Port
+       # type-param field type(most mapping the html input type)
+       type: number
+       # when type is number, range is required
+       range: '[0,65535]'
+    ```
 
-5. 将打包后的`jar`包，拷贝到安装目录下的`ext-lib`目录下（若为`docker`安装则先将`ext-lib`目录挂载出来，再拷贝到该目录下）
-   ![plugin-4.png](/img/docs/help/plugin-4.png)
+3. 在插件逻辑中使用参数
 
-6. 然后重启`HertzBeat`，即可实现自定义告警后处理策略。
+   ```java
+    @Override
+    public void execute(Alert alert, PluginContext pluginContext) {
+        log.info("param host:{}",pluginContext.getString("host"));
+        log.info("param port:{}",pluginContext.getInteger("port"));
+    }
+   ```