StarRocks AuditLoader 审计日志入库实战：架构原理、插件配置与运维指南-平芜编程栈

StarRocks AuditLoader 审计日志入库实战：架构原理、插件配置与运维指南

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

StarRocks 默认将审计日志写入 FE 节点的本地文件fe/log/fe.audit.log，而非内部数据库，这给跨节点检索、聚合统计与长期留痕带来不便。本指南以 StarRocks 官方插件AuditLoader为主线，完整讲解"建表承载审计日志 → 配置并安装插件 → 后台线程读取日志并通过 Stream Load 写入 → SQL 查询审计数据"的全流程，并结合仓库源码剖析其底层事件分发与字段映射机制，帮助你搭建一套可查询、可治理的审计日志分析体系。

AuditLoader 的工作原理

AuditLoader 是 StarRocks 提供的一款AUDIT 类型插件，安装后由 FE 启动后台线程持续读取本地审计日志文件，将其解析为结构化字段，再通过 HTTP PUT 形式的Stream Load写入用户预先创建的 StarRocks 表中，随后即可用标准 SQL 对审计日志进行查询与统计分析。

从源码层面看，审计日志的产生与分发链路如下：

审计事件生成：查询执行等关键路径上，FE 通过AuditEventBuilder构建审计事件对象AuditEvent（定义于 AuditEvent.java），其中所有需要落库/落盘的字段都用@AuditField注解标记。
事件入队分发：事件提交给 AuditEventProcessor.java（容量为 10000 的有界阻塞队列），其后台Worker线程每 60 秒刷新一次已安装的 AUDIT 插件列表，并将事件投递给每个符合条件的插件（eventFilter返回 true 时调用exec）。
默认落盘：内置插件__builtin_AuditLogBuilder（见 AuditLogBuilder.java）接收事件后，按@AuditField注解反射提取字段，写入fe.audit.log。它只处理BEFORE_QUERY、AFTER_QUERY、CONNECTION三类事件。
AuditLoader 入库：用户安装的 AuditLoader 插件同样实现AuditPlugin接口（eventFilter/exec，见 AuditPlugin.java），以独立线程批量读取日志并执行 Stream Load 写入目标表。

创建承载审计日志的库表

首先在集群中创建数据库与表，用于存放审计日志。建库建表语法可参考 CREATE DATABASE 与 CREATE TABLE。

CAUTION
不同 StarRocks 版本新增的审计字段并不一致，为规避升级带来的兼容性问题，建表时必须遵守以下约定：
所有新增字段必须标记为NULL。
字段不得重命名，用户可能依赖现有字段名。
字段类型只允许向后兼容的变更（例如VARCHAR(32)→VARCHAR(64)），避免写入时报错。
AuditEvent字段按名称解析，列的顺序无关紧要，可随时调整。
表中不存在对应列的AuditEvent字段会被静默忽略，因此你可以按需删减不需要的列。

推荐建表语句如下：

CREATE DATABASE starrocks_audit_db__; CREATE TABLE starrocks_audit_db__.starrocks_audit_tbl__ ( `queryId` VARCHAR(64) COMMENT "Unique ID of the query", `timestamp` DATETIME NOT NULL COMMENT "Query start time", `queryType` VARCHAR(12) COMMENT "Query type (query, slow_query, connection)", `clientIp` VARCHAR(32) COMMENT "Client IP", `user` VARCHAR(64) COMMENT "Query username", `authorizedUser` VARCHAR(64) COMMENT "Unique identifier of the user, i.e., user_identity", `resourceGroup` VARCHAR(64) COMMENT "Resource group name", `catalog` VARCHAR(32) COMMENT "Catalog name", `db` VARCHAR(96) COMMENT "Database where the query runs", `state` VARCHAR(8) COMMENT "Query state (EOF, ERR, OK)", `errorCode` VARCHAR(512) COMMENT "Error code", `errorMessage` VARCHAR(1048576) NULL COMMENT "Error message returned to the client", `queryTime` BIGINT COMMENT "Query execution time (milliseconds)", `scanBytes` BIGINT COMMENT "Number of bytes scanned by the query", `scanRows` BIGINT COMMENT "Number of rows scanned by the query", `returnRows` BIGINT COMMENT "Number of rows returned by the query", `cpuCostNs` BIGINT COMMENT "CPU time consumed by the query (nanoseconds)", `memCostBytes` BIGINT COMMENT "Memory consumed by the query (bytes)", `stmtId` INT COMMENT "Incremental ID of the SQL statement", `isQuery` TINYINT COMMENT "Whether the SQL is a query (1 or 0)", `feIp` VARCHAR(128) COMMENT "FE IP that executed the statement", `stmt` VARCHAR(1048576) COMMENT "Original SQL statement", `digest` VARCHAR(32) COMMENT "Fingerprint of slow SQL", `planCpuCosts` DOUBLE COMMENT "CPU usage during query planning (nanoseconds)", `planMemCosts` DOUBLE COMMENT "Memory usage during query planning (bytes)", `pendingTimeMs` BIGINT COMMENT "Time the query waited in the queue (milliseconds)", `candidateMVs` VARCHAR(65533) NULL COMMENT "List of candidate materialized views", `hitMvs` VARCHAR(65533) NULL COMMENT "List of matched materialized views", `QueriedRelations` ARRAY<VARCHAR(65533)> NULL COMMENT "List of directly referenced tables and views", `warehouse` VARCHAR(32) NULL COMMENT "Warehouse name" ) ENGINE = OLAP DUPLICATE KEY (`queryId`, `timestamp`, `queryType`) COMMENT "Audit log table" PARTITION BY date_trunc('day', `timestamp`) PROPERTIES ( "replication_num" = "1", "partition_live_number" = "30" );

上述表按timestamp以天为单位动态分区，partition_live_number = 30意味着仅保留最近 30 个分区的数据，起到自动回收历史审计日志的作用。表创建后，默认约 10 分钟生成第一个动态分区，届时即可开始接收审计日志。可用以下语句检查分区是否就绪：

SHOW PARTITIONS FROM starrocks_audit_db__.starrocks_audit_tbl__;

:::note 如果是从旧版本沿用已有审计表，需要补齐后续版本新增的列，否则对应字段会在加载时被静默丢弃。例如errorMessage在 v4.2.0 引入：

ALTER TABLE starrocks_audit_db__.starrocks_audit_tbl__ ADD COLUMN `errorMessage` VARCHAR(1048576) NULL COMMENT "Error message returned to the client" AFTER `errorCode`;

务必在配置 AuditLoader 的filter参数之前完成加列，因为 filter 是依据表列进行求值的。 :::

审计字段的来源解读

表中的字段与AuditEvent的@AuditField注解一一对应，从 AuditEvent.java 的源码可以看到更完整的字段清单，除建表语句中的常用列外，还包括Slots（查询占用的 slot 数）、SpilledBytes（落盘字节数）、writeClientTimeMs（写客户端耗时）、CNGroup、Features、PredictMemBytes、TransmittedBytes（传输字节数）、QuerySource、Command、SessionId、PreparedStmtId、CacheHitRatio（本地缓存命中率，仅存算分离共享数据模式计算）等。这些字段均可按需以相同命名添加到审计表中，从而获得更细粒度的查询画像。

部分字段的取值规则值得注意：

数值型字段的默认占位值为-1；被注解ignore_zero = true的字段（如cpuCostNs、memCostBytes）在值为 0 或 -1 时，内置审计日志写出时会跳过该列，避免日志中出现无意义占位。
errorMessage经过normalizeErrorMessage归一化处理：换行/竖线等分隔符会被替换为空格，长度受audit_log_error_message_max_length（默认 1024）约束，且开启enable_sql_desensitize_in_log时该字段会被清空，以规避敏感信息泄露。
QueriedRelations是ARRAY<VARCHAR>类型，记录查询直接引用的表与视图，例如["default_catalog.db1.tbl1","default_catalog.db1.view1"]。
pendingTimeMs为 -1 表示查询未经历排队等待；digest为慢 SQL 的指纹，可用于慢查询聚合分析。

下载与配置 AuditLoader 插件

下载与解压

下载 AuditLoader 安装包（auditloader.zip），该包与 StarRocks 所有可用版本兼容。
解压安装包：
```
unzip auditloader.zip
```
解压后得到三个文件：
- auditloader.jar：AuditLoader 的 JAR 包。
- plugin.properties：插件属性文件，无需修改。
- plugin.conf：插件配置文件，通常只需修改user与password。

配置 plugin.conf

修改plugin.conf，核心配置项如下：

配置项	说明
`frontend_host_port`	FE IP 与 HTTP 端口，格式`<fe_ip>:<fe_http_port>`，默认`127.0.0.1:8030`。每个 FE 独立管理自己的审计日志，插件安装后各 FE 各自启动后台线程抓取并写入。该参数用于指定后台 Stream Load 任务的 HTTP 地址，不支持多值；IP 部分虽可填集群中任一 FE，但不推荐——若该 FE 宕机，其他 FE 后台的审计写入任务也会因通信失败而中断。使用默认值可让每个 FE 走自身的 HTTP 端口，互不影响（所有写入任务最终都会转发到 FE Leader 执行）。
`database`	承载审计日志的数据库名。
`table`	承载审计日志的表名。
`user`	集群用户名，必须具备对目标表的 LOAD_PRIV 加载权限。
`password`	用户密码，是否加密取决于`secret_key`。
`secret_key`	用于加密密码的密钥（字符串，长度不超过 16 字节）。不设置时`password`填明文；设置后`password`需填密文，可在 StarRocks 中通过`SELECT TO_BASE64(AES_ENCRYPT('password','secret_key'));`生成。
`filter`	审计日志加载的过滤条件，基于 Stream Load 的 WHERE 参数（即`-H "where: <condition>"`），默认空字符串。示例：`filter=isQuery=1 and clientIp like '127.0.0.1%' and user='root'`。

filter的求值目标是目标表的列，因此被引用的字段必须已存在于表中（例如引用errorMessage前需先执行上文 ALTER TABLE 加列）。常用的过滤场景包括：只导入查询类日志（isQuery=1）、排除内部探测 SQL、按用户或客户端 IP 圈定范围等。关于 Stream Load 的 WHERE 语义可参考 STREAM_LOAD。

重新打包与分发

配置完成后，将文件重新打成安装包：

zip -q -m -r auditloader.zip auditloader.jar plugin.conf plugin.properties

随后把包分发到所有运行 FE 的机器，并确保所有机器上的包路径完全一致，否则安装失败。分发完成后记下包的绝对路径。

NOTE
也可以把auditloader.zip放到所有 FE 均可访问的 HTTP 服务（如httpd、nginx）上通过网络安装。无论哪种方式，安装完成后安装包都须保留在原路径，安装后不得删除源文件。

安装 AuditLoader

在 FE 上执行INSTALL PLUGIN语句并附上包的绝对路径即可完成安装：

INSTALL PLUGIN FROM "<absolute_path_to_package>";

若通过网络路径安装，需要在语句的 properties 中提供包的 md5 值，例如：

INSTALL PLUGIN FROM "http://xx.xx.xxx.xxx/extra/auditloader.zip" PROPERTIES("md5sum" = "3975F7B880C9490FE95F42E2B2A28E2D");

INSTALL PLUGIN的详细语法与约束可参考 INSTALL PLUGIN。从源码结构看，插件安装后由 FE 的插件管理器（PluginMgr）统一注册，AuditLoader 作为 AUDIT 类型插件会进入AuditEventProcessor每分钟刷新一次的活跃插件列表，从而接管审计事件的消费。

验证安装并查询审计日志

检查插件状态

通过SHOW PLUGINS确认安装结果，SHOW PLUGINS 是查看插件状态的标准语句：

mysql> SHOW PLUGINS\G *************************** 1. row *************************** Name: __builtin_AuditLogBuilder Type: AUDIT Description: builtin audit logger Version: 0.12.0 JavaVersion: 1.8.31 ClassName: com.starrocks.qe.AuditLogBuilder SoName: NULL Sources: Builtin Status: INSTALLED Properties: {} *************************** 2. row *************************** Name: AuditLoader Type: AUDIT Description: Available for versions 3.3.11+. Load audit log to starrocks, and user can view the statistic of queries Version: 5.0.0 JavaVersion: 11 ClassName: com.starrocks.plugin.audit.AuditLoaderPlugin SoName: NULL Sources: /x/xx/xxx/xxxxx/auditloader.zip Status: INSTALLED Properties: {} 2 rows in set (0.01 sec)

输出中同时包含两个 AUDIT 插件：第一行是 FE 启动即注册的内置审计日志写出插件__builtin_AuditLogBuilder（对应源码 AuditLogBuilder.java），第二行是刚安装的AuditLoader。当AuditLoader的Status显示为INSTALLED时，即表示安装成功。

触发并查询审计日志

执行若干随机 SQL 以产生审计日志。
等待约 60 秒（或你在plugin.conf中通过max_batch_interval_sec指定的批量写入间隔），让 AuditLoader 将日志加载进表。

查询审计表：

SELECT * FROM starrocks_audit_db__.starrocks_audit_tbl__;

加载成功的示例输出：

mysql> SELECT * FROM starrocks_audit_db__.starrocks_audit_tbl__\G *************************** 1. row *************************** queryId: 01975a33-4129-7520-97a2-05e641cec6c9 timestamp: 2025-06-10 14:16:37 queryType: query clientIp: xxx.xx.xxx.xx:65283 user: root authorizedUser: 'root'@'%' resourceGroup: default_wg catalog: default_catalog db: state: EOF errorCode: queryTime: 3 scanBytes: 0 scanRows: 0 returnRows: 1 cpuCostNs: 33711 memCostBytes: 4200 stmtId: 102 isQuery: 1 feIp: xxx.xx.xxx.xx stmt: SELECT * FROM starrocks_audit_db__.starrocks_audit_tbl__ digest: planCpuCosts: 908 planMemCosts: 0 pendingTimeMs: -1 candidateMvs: null hitMVs: null

QueriedRelations: ["default_catalog.db1.tbl1","default_catalog.db1.view1"] …………

可以看到 `QueriedRelations` 以数组形式记录了查询引用的表与视图，`candidateMvs`/`hitMVs` 记录了物化视图的候选与命中情况，这些字段可用于慢查询优化与物化视图收益分析。 ### 结合配置项的运维提示 审计日志的本地产出行为由 FE 配置控制，相关配置项位于 [Config.java](https://link.gitcode.com/i/0a1b4251ba005744c55307f118897316)（对应 `conf/fe.conf`）： - `audit_log_dir`（默认 `${STARROCKS_HOME}/log`）：审计日志目录，即 fe.audit.log 所在位置。 - `audit_log_modules`（默认 `{"slow_query", "query"}`）与 `qe_slow_log_ms`（默认 5000，毫秒）：控制哪些模块、超过多少耗时被记入日志，`enable_qe_slow_log` 控制慢查询日志开关。 - `audit_log_roll_interval`（默认 `DAY`）、`audit_log_roll_num`（默认 90）、`audit_log_delete_age`（默认 `30d`）：控制日志按天滚动、保留份数与清理策略。 - `audit_log_json_format`（默认 false）：置为 true 时审计日志以 JSON 格式输出。 - `audit_log_error_message_max_length`（默认 1024）：错误消息的最大长度，超长截断。 - `audit_log_enable_compress`（默认 false）：是否压缩历史审计日志文件。 合理搭配上述配置与审计表的分区保留策略，可以在本地文件与入库表两层同时控制审计数据的生命周期。 ## 常见问题排查 如果动态分区已创建、插件也安装成功，但表中始终没有审计日志，优先检查 **plugin.conf** 配置是否正确。修改配置需要先卸载插件： ```SQL UNINSTALL PLUGIN AuditLoader;

AuditLoader 的运行日志会输出到fe.log，可在其中搜索关键字audit定位失败原因。常见的排查方向包括：

frontend_host_port指向的 FE 端口不可达或填写了多个值；
user对目标表缺少LOAD_PRIV权限；
database/table名称与建库建表语句不一致；
filter引用了表中不存在的列，导致求值失败；
secret_key与加密密码不匹配，或密钥超过 16 字节；
各 FE 节点上的安装包路径不一致。

配置修正后，重新执行安装步骤即可。UNINSTALL PLUGIN的详细用法可参考 UNINSTALL_PLUGIN。

总结

AuditLoader 将 StarRocks 分散在本地文件中的审计日志转化为可 SQL 查询的结构化数据，其完整链路——内置AuditLogBuilder落盘、AuditEventProcessor事件分发、AuditLoader 后台线程经 Stream Load 入库——均可从 fe/fe-core/src/main/java/com/starrocks/qe 与 fe/fe-core/src/main/java/com/starrocks/plugin 的源码中追溯验证。按本文步骤完成建表、配置、安装与验证后，即可基于审计表开展用户行为分析、慢查询治理、资源组用量统计与安全审计等日常工作。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考