Doris 插件框架

介绍

Doris 的插件框架支持在运行时添加/卸载自定义插件，而不需要重启服务，用户可以通过开发自己的插件来扩展Doris的功能。

例如，审计插件作用于 Doris 请求执行后，可以获取到一次请求相关的信息（访问用户，请求IP，SQL等…），并将信息写入到指定的表中。

与UDF的区别：

  • UDF是函数，用于在SQL执行时进行数据计算。插件是附加功能，用于为Doris扩展自定义的功能，例如：支持不同的存储引擎，支持不同的导入方式，插件并不会参与执行SQL时的数据计算。
  • UDF的执行周期仅限于一次SQL执行。插件的执行周期可能与Doris进程相同。
  • 使用场景不同。如果您需要执行SQL时支持特殊的数据算法，那么推荐使用UDF，如果您需要在Doris上运行自定义的功能，或者是启动一个后台线程执行任务，那么推荐使用插件。

目前插件框架仅支持审计类插件。

注意: Doris的插件框架是实验性功能, 目前只支持FE插件，且默认是关闭的，可以通过FE配置plugin_enable=true打开

插件

一个FE的插件可以使一个zip压缩包或者是一个目录。其内容至少包含两个文件：plugin.properties 和 .jar 文件。plugin.properties用于描述插件信息。

文件结构如下：

  1. # plugin .zip
  2. auditodemo.zip:
  3.     -plugin.properties
  4.     -auditdemo.jar
  5.     -xxx.config
  6.     -data/
  7.     -test_data/
  9. # plugin local directory
  10. auditodemo/:
  11.     -plugin.properties
  12.     -auditdemo.jar
  13.     -xxx.config
  14.     -data/
  15.     -test_data/

plugin.properties 内容示例:

  1. ### required:
  2. #
  3. # the plugin name
  4. name = audit_plugin_demo
  5. #
  6. # the plugin type
  7. type = AUDIT
  8. #
  9. # simple summary of the plugin
  10. description = just for test
  11. #
  12. # Doris's version, like: 0.11.0
  13. version = 0.11.0
  15. ### FE-Plugin optional:
  16. #
  17. # version of java the code is built against
  18. # use the command "java -version" value, like 1.8.0, 9.0.1, 13.0.4
  19. java.version = 1.8.31
  20. #
  21. # the name of the class to load, fully-qualified.
  22. classname = AuditPluginDemo
  24. ### BE-Plugin optional:
  25. # the name of the so to load
  26. soName = example.so

编写插件

插件的开发环境依赖Doris的开发编译环境。所以请先确保Doris的开发编译环境运行正常。

fe_plugins 目录是 FE 插件的根模块。这个根模块统一管理插件所需的依赖。添加一个新的插件，相当于在这个根模块添加一个子模块。

创建插件模块

我们可以通过以下命令在 fe_plugins 目录创建一个子模块用户实现创建和创建工程。其中 doris-fe-test 为插件名称。

  1. mvn archetype: generate -DarchetypeCatalog = internal -DgroupId = org.apache -DartifactId = doris-fe-test -DinteractiveMode = false

这个命令会创建一个新的 maven 工程，并且自动向 fe_plugins/pom.xml 中添加一个子模块：

  1.     .....
  2.     <groupId>org.apache</groupId>
  3.     <artifactId>doris-fe-plugins</artifactId>
  4.     <packaging>pom</packaging>
  5.     <version>1.0-SNAPSHOT</version>
  6.     <modules>
  7.         <module>auditdemo</module>
  8.         # new plugin module
  9.         <module>doris-fe-test</module>
  10.     </modules>
  11.     .....

新的工程目录结构如下：

  1. -doris-fe-test/
  2. -pom.xml
  3. -src/
  4.     ---- main/java/org/apache/
  5.     ------- App.java # mvn auto generate, ignore
  6.     ---- test/java/org/apache

接下来我们在 main 目录下添加一个 assembly 目录来存放 plugin.properties 和 zip.xml。最终的工程目录结构如下：

  1. -doris-fe-test/
  2. -pom.xml
  3. -src/
  4. ---- main/
  5. ------ assembly/
  6. -------- plugin.properties
  7. -------- zip.xml
  8. ------ java/org/apache/
  9. --------App.java # mvn auto generate, ignore
  10. ---- test/java/org/apache

添加 zip.xml

zip.xml 用于描述最终生成的 zip 压缩包中的文件内容。（如 .jar file, plugin.properties 等等）

  1. <assembly>
  2.     <id>plugin</id>
  3.     <formats>
  4.         <format>zip</format>
  5.     </formats>
  6.     <!-IMPORTANT: must be false->
  7.     <includeBaseDirectory>false</includeBaseDirectory>
  8.     <fileSets>
  9.         <fileSet>
  10.             <directory>target</directory>
  11.             <includes>
  12.                 <include>*.jar</include>
  13.             </ ncludes>
  14.             <outputDirectory>/</outputDirectory>
  15.         </fileSet>
  17.         <fileSet>
  18.             <directory>src/main/assembly</directory>
  19.             <includes>
  20.                 <include>plugin.properties</include>
  21.             </includes>
  22.             <outputDirectory>/</outputDirectory>
  23.         </fileSet>
  24.     </fileSets>
  25. </assembly>

更新 pom.xml

接下来我们需要更新子模块的 pom.xml 文件，添加 doris-fe 依赖：

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  3.          xmlns="http://maven.apache.org/POM/4.0.0"
  4.          xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  5.     <parent>
  6.         <groupId>org.apache</groupId>
  7.         <artifactId>doris-fe-plugins</artifactId>
  8.         <version>1.0-SNAPSHOT</version>
  9.     </parent>
  10.     <modelVersion>4.0.0</modelVersion>
  12.     <artifactId>auditloader</artifactId>
  13.     <packaging>jar</packaging>
  15.     <dependencies>
  16.         <!-- doris-fe dependencies -->
  17.         <dependency>
  18.             <groupId>org.apache</groupId>
  19.             <artifactId>doris-fe</artifactId>
  20.         </dependency>
  22.         <!-- other dependencies -->
  23.         <dependency>
  24.             ...
  25.         </dependency>
  26.     </dependencies>
  28.     <build>
  29.         <finalName>auditloader</finalName>
  30.         <plugins>
  31.             <plugin>
  32.                 <artifactId>maven-assembly-plugin</artifactId>
  33.                 <version>2.4.1</version>
  34.                 <configuration>
  35.                     <appendAssemblyId>false</appendAssemblyId>
  36.                     <descriptors>
  37.                         <descriptor>src/main/assembly/zip.xml</descriptor>
  38.                     </descriptors>
  39.                 </configuration>
  40.                 <executions>
  41.                     <execution>
  42.                         <id>make-assembly</id>
  43.                         <phase>package</phase>
  44.                         <goals>
  45.                             <goal>single</goal>
  46.                         </goals>
  47.                     </execution>
  48.                 </executions>
  49.             </plugin>
  50.         </plugins>
  51.     </build>
  53. </project>

实现插件

之后我们就可以开始进行插件功能的开发了。插件需要实现 Plugin 接口。具体可以参阅 Doris 自带的 auditdemo 插件示例代码。

编译

在编译插件之前，需要先执行 sh build.sh --fe 进行 Doris FE 代码的编译，并确保编译成功。

之后，执行 sh build_plugin.sh 编译所有插件。最终的产出会存放在 fe_plugins/output 目录中。

或者也可以执行 sh build_plugin.sh --plugin your_plugin_name 来仅编译指定的插件。

另一种开发方式

您可以直接通过修改自带的 auditdemo 插件示例代码进行开发。

部署

插件可以通过以下三种方式部署。

  • 将 .zip 文件放在 Http 或 Https 服务器上。如：http://xxx.xxx.com/data/my_plugin.zip, Doris 会下载这个文件。同时需要在properties中设置md5sum的值，或者放置一个和 .zip 文件同名的 md5 文件，如 http://xxx.xxxxxx.com/data/my_plugin.zip.md5。其中内容为 .zip 文件的 MD5 值。
  • 本地 .zip 文件。 如：/home/work/data/plugin.zip。如果该插件仅用于 FE，则需部署在所有 FE 节点相同的目录下。否则，需要在所有 FE 和 BE 节点部署。
  • 本地目录。如：/home/work/data/plugin/。相当于 .zip 文件解压后的目录。如果该插件仅用于 FE，则需部署在所有 FE 节点相同的目录下。否则，需要在所有 FE 和 BE 节点部署。

注意：需保证部署路径在整个插件生命周期内有效。

安装和卸载插件

通过如下命令安装和卸载插件。更多帮助请参阅 HELP INSTALL PLUGIN; HELP IUNNSTALL PLUGIN; HELP SHOW PLUGINS;

  1. mysql> install plugin from "/home/users/doris/auditloader.zip";
  2. Query OK, 0 rows affected (0.09 sec)
  4. mysql> show plugins\G
  5. *************************** 1. row ***************************
  6.        Name: auditloader
  7.        Type: AUDIT
  8. Description: load audit log to olap load, and user can view the statistic of queries
  9.     Version: 0.12.0
  10. JavaVersion: 1.8.31
  11.   ClassName: AuditLoaderPlugin
  12.      SoName: NULL
  13.     Sources: /home/users/doris/auditloader.zip
  14.      Status: INSTALLED
  15.  Properties: {}
  16. *************************** 2. row ***************************
  17.        Name: AuditLogBuilder
  18.        Type: AUDIT
  19. Description: builtin audit logger
  20.     Version: 0.12.0
  21. JavaVersion: 1.8.31
  22.   ClassName: org.apache.doris.qe.AuditLogBuilder
  23.      SoName: NULL
  24.     Sources: Builtin
  25.      Status: INSTALLED
  26.  Properties: {}   
  27. 2 rows in set (0.00 sec)
  29. mysql> uninstall plugin auditloader;
  30. Query OK, 0 rows affected (0.05 sec)
  32. mysql> show plugins;
  33. Empty set (0.00 sec)