You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dolphinscheduler.apache.org by ki...@apache.org on 2021/08/12 15:34:44 UTC
[dolphinscheduler-website] branch master updated: [Summer2021]
Translate the alert_spi.md (#405)
This is an automated email from the ASF dual-hosted git repository.
kirs pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dolphinscheduler-website.git
The following commit(s) were added to refs/heads/master by this push:
new 0306953 [Summer2021] Translate the alert_spi.md (#405)
0306953 is described below
commit 0306953623303d761628e1df475be6c44b222991
Author: QuakeWang <45...@users.noreply.github.com>
AuthorDate: Thu Aug 12 23:34:39 2021 +0800
[Summer2021] Translate the alert_spi.md (#405)
Update the mistakes.
---
docs/en-us/dev/user_doc/alert_spi.md | 104 +++++++++++++++++++++++++++++++++++
docs/zh-cn/dev/user_doc/alert_spi.md | 45 +++++++--------
2 files changed, 124 insertions(+), 25 deletions(-)
diff --git a/docs/en-us/dev/user_doc/alert_spi.md b/docs/en-us/dev/user_doc/alert_spi.md
index e69de29..0e3b5c4 100644
--- a/docs/en-us/dev/user_doc/alert_spi.md
+++ b/docs/en-us/dev/user_doc/alert_spi.md
@@ -0,0 +1,104 @@
+### DolphinScheduler Alert SPI main design
+
+#### DolphinScheduler SPI Design
+
+The architecture of microkernel & plug-in of DolphinScheduler is changing. All core capabilities such as tasks, resource storage, registry, etc. will be designed to be extensions, and we want to improve the flexibility as well as the friendliness (extensibility) of DolphinScheduler itself through SPI.
+
+You can read the relevant code under the dolphinscheduler-spi module as a reference. The extended interface of the associated plug-in is under the module, and when we need to implement the relevant function plug-in, it is recommended to read this code block first. Of course, you are welcomed to read the documentation, which will save a lot less time. However, the documentation has a certain lag and when it is missing, it is suggested to take the source code as the reference (If you are i [...]
+
+When you need to extend, you actually only need to focus on the extension interface. For example, for the alert service you only need to focus on the AlertChannelFactory and the AlertChannel. The underlying logic is already implemented by DolphinScheduler, which makes our development much more focused and simpler.
+
+By the way, we use an excellent front-end component, form-create, which supports the generation of front-end ui components based on json. If plugin development involves a front-end, we will use json to generate the relevant front-end UI components. The parameters of the plugin are wrapped in org.apache.dolphinscheduler.spi.params, which converts all the relevant parameters into json, meaning that you can draw the front-end components (mainly forms here, we only care about the data of fro [...]
+
+This article focuses on the design and development of Alert alerts.
+
+#### Main Modules
+
+If you don't care about its internal design, and just want to know how to develop your own alarm plugin, you can skip this section.
+
+* dolphinscheduler-spi
+
+ This module is the core SPI module and provides the basic SPI relevant behaviour, where dolphinschedulerplugin is the plugin top-layer interface, all DolphinsCheduler's plugins must implement the interface, and the module also provides some universal tool classes (if you can detach it again Some will something will be better? For example, the UI, we currently use the parameter part) and some UI related basic information.
+
+* dolphinscheduler-alert
+
+ In this module, we have implemented the load of the associated plugin when the Alert-Server starts. Alert provides a variety of plug-in configuration methods that can be enabled by simple configurations after you have done the development. The configuration file is located at dolphinscheduler-alert/src/main/resources/alert.properties .
+
+ It provides two methods of configuration.
+
+ 1: Configure the jar directory specified by the plugin, eg: alert.plugin.dir=/root/dolphinscheduler/lib/plugin/alert . When alert-server starts, it will load the jar of the relevant plugin from the specified directory.
+
+ 2: IDE development mode
+
+ You can use this configuration when you are in the debugging phase of development, see [dolphinscheduler-maven-plugin](https://github.com/apache/incubator-dolphinscheduler-maven-plugin) for design principles.
+
+
+
+ * Packaging plugins
+
+ We use provisio, an excellent packaging tool, for packaging plugins. Please add it to dolphinscheduler-dist/src/main/provisio/dolphinscheduler.xml, and it will package plugins to the specified directory when processed.
+
+
+
+#### Alert SPI Main class information.
+
+AlertChannelFactory
+All alert plugins need to implement this interface. The interface is used to define the name of the alert plugin and the required parameters.
+
+AlertChannel
+The interface of the alarm plug-in. The alarm plugin needs to implement the interface. It only has one method process. The upper alarm system calls the method and gets the return information of the alert by the AlertResult returned by this method.
+
+AlertData
+Alert content information. It includes id, title, content and log.
+
+AlertInfo
+Alarm-related information. When the upper system calls the alarm plug-in instance, the instance of this class is incorporated into the specific alarm plugin through the Process method. It contains the parameter information filled in the front end of the alarm content AlertData and the called alarm plugin instance.
+
+AlertResult
+The alert plugin sends an alert return message.
+
+org.apache.dolphinscheduler.spi.params
+This package contains the plug-in parameter definitions. We use alpacajs, a front-end library http://www.form-create.com, which dynamically generates the front-end ui based on the parameter list json returned by the plug-in definition, so we don't need to care about the front-end when doing SPI plug-in development.
+
+Inside this package we currently only wrap RadioParam, TextParam and PasswordParam, which are used to define parameters of text, radio and password respectively.
+
+AbsPluginParams
+
+This class is the base class for all parameters and is inherited by the RadioParam classes. Each DS alert plugin returns a list of AbsPluginParams in the AlertChannelFactory implementation.
+
+The specific design of alert_spi can be found in issue: [Alert Plugin Design](https://github.com/apache/incubator-dolphinscheduler/issues/3049)
+
+#### Alert SPI built-in implementation
+
+* Email
+
+ Email alert notification
+
+* DingTalk
+
+ Alert for DingTalk group chat bots
+
+* EnterpriseWeChat
+
+ EnterpriseWeChat alert notifications
+
+ Related parameter configuration can refer to the EnterpriseWeChat robot document.
+
+* Script
+
+ We have implemented a shell script for alerting. We will pass the relevant alert parameters to the script and you can implement your alert logic in the shell. This is a good way to interface with internal alerting applications.
+
+* SMS
+
+ SMS alerts
+
+#### Alarm Custom Plugin Development
+
+In fact, it's very easy to implement a plugin by yourself, you only need to care about the plugin extension interface. In Alert you only need to care about the AlertChannelFactory and AlertChannel. We would recommend that you follow the design specifications of other built-in plugins so that when your idea is good enough, you can donate it to the community without having to change it too much.
+
+When you have finished developing the relevant code, configure the relevant plug-ins in alert.properties (or just configure a plug-in directory and it will load all the plug-ins in that directory).
+
+
+Then, you can happily start using your own plugins.
+
+In fact, custom plug-in development is as easy as we described, and not as difficult as you imagined.
diff --git a/docs/zh-cn/dev/user_doc/alert_spi.md b/docs/zh-cn/dev/user_doc/alert_spi.md
index e6f838a..574d92b 100644
--- a/docs/zh-cn/dev/user_doc/alert_spi.md
+++ b/docs/zh-cn/dev/user_doc/alert_spi.md
@@ -2,58 +2,53 @@
#### DolphinScheduler SPI 设计
-DolphinScheduler 正在处于微内核+插件化的架构更改之中，所有核心能力如任务、资源存储、注册中心等都将被设计为扩展点，我们希望通过SPI来提高DolphinScheduler本身的灵活性以及友好性（扩展性）
-。
+DolphinScheduler 正在处于微内核 + 插件化的架构更改之中，所有核心能力如任务、资源存储、注册中心等都将被设计为扩展点，我们希望通过 SPI 来提高 DolphinScheduler 本身的灵活性以及友好性（扩展性）。
-相关代码可以参考 dolphinscheduler-spi 模块。相关插件的扩展接口皆在该模块下，当我们需要实现相关功能的插件化的时候，建议先阅读此块的代码，当然，更建议您阅读文档，这会减少很多时间，不过文档有一定的后滞性，当文档缺失的时候，建议以源码为准（如果有兴趣，我们也欢迎你来提交相关文档），此外，我们几乎不会对扩展接口做变更（不包括新增），除非重大架构调整，出现不兼容升级版本，因此，现有文档一般都能够满足。
+相关代码可以参考 dolphinscheduler-spi 模块。相关插件的扩展接口皆在该模块下，当我们需要实现相关功能的插件化的时候，建议先阅读此块的代码，当然，更建议你阅读文档，这会减少很多时间，不过文档有一定的后滞性，当文档缺失的时候，建议以源码为准（如果有兴趣，我们也欢迎你来提交相关文档），此外，我们几乎不会对扩展接口做变更（不包括新增），除非重大架构调整，出现不兼容升级版本，因此，现有文档一般都能够满足。
-当您需要扩展的时候，事实上您只需要关注扩展接口即可，比如告警服务，您只需要关注AlertChannelFactory 以及AlertChannel 即可。底层相关逻辑DolphinScheduler已经帮我们实现，这让我们的开发更加专注且简单。
+当你需要扩展的时候，事实上你只需要关注扩展接口即可，比如告警服务，您只需要关注 AlertChannelFactory 以及 AlertChannel 即可。底层相关逻辑 DolphinScheduler 已经帮我们实现，这让我们的开发更加专注且简单。
-顺便提一句，我们采用了一款优秀的前端组件form-create，它支持基于json生成前端ui组件，如果插件开发牵扯到前端，我们会通过json来生成相关前端UI组件，org.apache.dolphinscheduler.spi.params 里面对插件的参数做了封装，它会将相关参数全部全部转化为对应的json，这意味这你完全可以通过Java代码的方式完成前端组件的绘制（这里主要是表单，我们只关心前后端交互的数据）。
+顺便提一句，我们采用了一款优秀的前端组件 form-create，它支持基于 json 生成前端 ui 组件，如果插件开发牵扯到前端，我们会通过 json 来生成相关前端 UI 组件，org.apache.dolphinscheduler.spi.params 里面对插件的参数做了封装，它会将相关参数全部全部转化为对应的 json，这意味这你完全可以通过 Java 代码的方式完成前端组件的绘制（这里主要是表单，我们只关心前后端交互的数据）。
-本文主要着重讲解Alert告警相关设计以及开发，
+本文主要着重讲解 Alert 告警相关设计以及开发。
#### 主要模块
-如果您并不关心它的内部设计，只是想单纯的了解如何开发自己的告警插件，您可以略过该内容。
+如果你并不关心它的内部设计，只是想单纯的了解如何开发自己的告警插件，可以略过该内容。
* dolphinscheduler-spi
- 该模块是SPI的核心模块，提供了SPI相关的基础行为，其中 DolphinSchedulerPlugin 为插件顶层接口，所有DolphinScheduler 的插件都必须实现该接口，另外该模块也提供了一些通用的工具类（如果能够再抽离出去一些会不会更好？比如UI，我们目前就Alert用到了参数这块）以及一些UI相关的基础信息。
+ 该模块是 SPI 的核心模块，提供了 SPI 相关的基础行为，其中 DolphinSchedulerPlugin 为插件顶层接口，所有 DolphinScheduler 的插件都必须实现该接口，另外该模块也提供了一些通用的工具类（如果能够再抽离出去一些会不会更好？比如 UI，我们目前就 Alert 用到了参数这块）以及一些 UI 相关的基础信息。
* dolphinscheduler-alert
- 在这个模块，我们实现了在alert-server 启动的时候相关插件的加载。
-
- alert提供了多种插件配置方法，当你开发工作完成后，通过简单的配置即可启用。
-
- 配置文件位于 dolphinscheduler-alert/src/main/resources/alert.properties
+ 在这个模块，我们实现了在 alert-server 启动的时候相关插件的加载。alert 提供了多种插件配置方法，当你开发工作完成后，通过简单的配置即可启用。配置文件位于 dolphinscheduler-alert/src/main/resources/alert.properties
它提供了两种配置方法：
- 1:配置插件指定的jar目录，eg：alert.plugin.dir=/root/dolphinscheduler/lib/plugin/alert . 当alert-server启动时，会从指定目录加载相关插件的jar。
+ 1：配置插件指定的 jar 目录，eg：alert.plugin.dir=/root/dolphinscheduler/lib/plugin/alert . 当alert-server启动时，会从指定目录加载相关插件的jar。
- 2: IDE开发模式
+ 2：IDE开发模式
- 当你处于开发调试阶段的时候，你可以采用该配置，相关设计原理参照[dolphinscheduler-maven-plugin](https://github.com/apache/incubator-dolphinscheduler-maven-plugin)
+ 当你处于开发调试阶段的时候，你可以采用该配置，相关设计原理参照 [dolphinscheduler-maven-plugin](https://github.com/apache/incubator-dolphinscheduler-maven-plugin)
-* 3:打包插件
+ * 打包插件
- 插件打包我们使用了[provisio](https://github.com/jvanzyl/provisio),这是一款优秀的打包工具，你需要在完成插件开发后将其添加到dolphinscheduler-dist/src/main/provisio/dolphinscheduler.xml，他会在执行的时候将插件打包至指定目录。
+ 插件打包我们使用了 [provisio](https://github.com/jvanzyl/provisio)，这是一款优秀的打包工具，你需要在完成插件开发后将其添加到 dolphinscheduler-dist/src/main/provisio/dolphinscheduler.xml，它会在执行的时候将插件打包至指定目录。
#### Alert SPI 主要类信息：
AlertChannelFactory
-告警插件工厂接口，所有告警插件需要实现该接口，该接口用来定义告警插件的名称，需要的参数，create 方法用来创建具体的告警插件实例.
+告警插件工厂接口，所有告警插件需要实现该接口，该接口用来定义告警插件的名称，需要的参数，create 方法用来创建具体的告警插件实例。
AlertChannel
告警插件的接口，告警插件需要实现该接口，该接口中只有一个方法 process ，上层告警系统会调用该方法并通过该方法返回的 AlertResult 来获取告警的返回信息。
AlertData
-告警内容信息，包括id，标题，内容，日志。
+告警内容信息，包括 id，标题，内容，日志。
AlertInfo
告警相关信息，上层系统调用告警插件实例时，将该类的实例通过 process 方法传入具体的告警插件。内部包含告警内容 AlertData 和调用的告警插件实例的前端填写的参数信息。
@@ -62,13 +57,13 @@ AlertResult
告警插件发送告警返回信息。
org.apache.dolphinscheduler.spi.params
-该包下是插件化的参数定义，我们前端使用alpacajs这个前端库http://www.form-create.com/，该库可以基于插件定义返回的参数列表json来动态生成前端的ui，因此我们在做SPI插件开发的时候无需关心前端。
+该包下是插件化的参数定义，我们前端使用 alpacajs 这个前端库 http://www.form-create.com，该库可以基于插件定义返回的参数列表 json 来动态生成前端的 ui，因此我们在做 SPI 插件开发的时候无需关心前端。
该 package 下我们目前只封装了 RadioParam，TextParam，PasswordParam，分别用来定义 text 类型的参数，radio 参数和 password 类型的参数。
-AbsPluginParams 该类是所有参数的基类，RadioParam这些类都继承了该类。每个DS的告警插件都会在 AlertChannelFactory 的实现中返回一个 AbsPluginParams 的 list。
+AbsPluginParams 该类是所有参数的基类，RadioParam 这些类都继承了该类。每个 DS 的告警插件都会在 AlertChannelFactory 的实现中返回一个 AbsPluginParams 的 list。
-alert_spi 具体设计可见issue :[Alert Plugin Design](https://github.com/apache/incubator-dolphinscheduler/issues/3049)
+alert_spi 具体设计可见 issue：[Alert Plugin Design](https://github.com/apache/incubator-dolphinscheduler/issues/3049)
#### Alert SPI 内置实现
@@ -87,7 +82,7 @@ alert_spi 具体设计可见issue :[Alert Plugin Design](https://github.com/apac
相关参数配置可以参考企业微信机器人文档。
* Script
- 我们实现了Shell脚本告警，我们会将相关告警参数透传给脚本，你可以在 Shell 中实现你的相关告警逻辑，如果你需要对接内部告警应用，这是一种不错的方法。
+ 我们实现了 Shell 脚本告警，我们会将相关告警参数透传给脚本，你可以在 Shell 中实现你的相关告警逻辑，如果你需要对接内部告警应用，这是一种不错的方法。
* SMS
@@ -102,4 +97,4 @@ alert_spi 具体设计可见issue :[Alert Plugin Design](https://github.com/apac
然后，接下来就可以开始愉快的使用你自己的插件了。
-事实上，自定义插件化开发确实如同我描绘的那么简单，并没有想象中的多么困难。
\ No newline at end of file
+事实上，自定义插件化开发确实如同我们描绘的那么简单，并没有想象中的多么困难。