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/
  8. # plugin local directory
  9. auditodemo/:
  10. -plugin.properties
  11. -auditdemo.jar
  12. -xxx.config
  13. -data/
  14. -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
  14. ### FE-Plugin optional:
  15. #
  16. # version of java the code is built against
  17. # use the command "java -version" value, like 1.8.0, 9.0.1, 13.0.4
  18. java.version = 1.8.31
  19. #
  20. # the name of the class to load, fully-qualified.
  21. classname = AuditPluginDemo
  22. ### BE-Plugin optional:
  23. # the name of the so to load
  24. 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.propertieszip.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>
  16. <fileSet>
  17. <directory>src/main/assembly</directory>
  18. <includes>
  19. <include>plugin.properties</include>
  20. </includes>
  21. <outputDirectory>/</outputDirectory>
  22. </fileSet>
  23. </fileSets>
  24. </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>
  11. <artifactId>auditloader</artifactId>
  12. <packaging>jar</packaging>
  13. <dependencies>
  14. <!-- doris-fe dependencies -->
  15. <dependency>
  16. <groupId>org.apache</groupId>
  17. <artifactId>doris-fe</artifactId>
  18. </dependency>
  19. <!-- other dependencies -->
  20. <dependency>
  21. ...
  22. </dependency>
  23. </dependencies>
  24. <build>
  25. <finalName>auditloader</finalName>
  26. <plugins>
  27. <plugin>
  28. <artifactId>maven-assembly-plugin</artifactId>
  29. <version>2.4.1</version>
  30. <configuration>
  31. <appendAssemblyId>false</appendAssemblyId>
  32. <descriptors>
  33. <descriptor>src/main/assembly/zip.xml</descriptor>
  34. </descriptors>
  35. </configuration>
  36. <executions>
  37. <execution>
  38. <id>make-assembly</id>
  39. <phase>package</phase>
  40. <goals>
  41. <goal>single</goal>
  42. </goals>
  43. </execution>
  44. </executions>
  45. </plugin>
  46. </plugins>
  47. </build>
  48. </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.xxxxxx.com/data/plugin.zip, Doris 会下载这个文件。
  • 本地 .zip 文件。 如:/home/work/data/plugin.zip。需要在所有 FE 和 BE 节点部署。
  • 本地目录。如:/home/work/data/plugin/。相当于 .zip 文件解压后的目录。需要在所有 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)
  3. mysql> mysql> show plugins\G
  4. *************************** 1. row ***************************
  5. Name: auditloader
  6. Type: AUDIT
  7. Description: load audit log to olap load, and user can view the statistic of queries
  8. Version: 0.12.0
  9. JavaVersion: 1.8.31
  10. ClassName: AuditLoaderPlugin
  11. SoName: NULL
  12. Sources: /home/users/doris/auditloader.zip
  13. Status: INSTALLED
  14. *************************** 2. row ***************************
  15. Name: AuditLogBuilder
  16. Type: AUDIT
  17. Description: builtin audit logger
  18. Version: 0.12.0
  19. JavaVersion: 1.8.31
  20. ClassName: org.apache.doris.qe.AuditLogBuilder
  21. SoName: NULL
  22. Sources: Builtin
  23. Status: INSTALLED
  24. 2 rows in set (0.00 sec)
  25. mysql> uninstall plugin auditloader;
  26. Query OK, 0 rows affected (0.05 sec)
  27. mysql> show plugins;
  28. Empty set (0.00 sec)