StarRocks AuditLoader 审计日志入库实战架构原理、插件配置与运维指南【免费下载链接】starrocksThe worlds 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/starrocksStarRocks 默认将审计日志写入 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 ARRAYVARCHAR(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是ARRAYVARCHAR类型记录查询直接引用的表与视图例如[default_catalog.db1.tbl1,default_catalog.db1.view1]。pendingTimeMs为 -1 表示查询未经历排队等待digest为慢 SQL 的指纹可用于慢查询聚合分析。下载与配置 AuditLoader 插件下载与解压下载 AuditLoader 安装包auditloader.zip该包与 StarRocks 所有可用版本兼容。解压安装包unzip auditloader.zip解压后得到三个文件auditloader.jarAuditLoader 的 JAR 包。plugin.properties插件属性文件无需修改。plugin.conf插件配置文件通常只需修改user与password。配置 plugin.conf修改plugin.conf核心配置项如下配置项说明frontend_host_portFE 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默认空字符串。示例filterisQuery1 and clientIp like 127.0.0.1% and userroot。filter的求值目标是目标表的列因此被引用的字段必须已存在于表中例如引用errorMessage前需先执行上文 ALTER TABLE 加列。常用的过滤场景包括只导入查询类日志isQuery1、排除内部探测 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: nullQueriedRelations: [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 的源码中追溯验证。按本文步骤完成建表、配置、安装与验证后即可基于审计表开展用户行为分析、慢查询治理、资源组用量统计与安全审计等日常工作。【免费下载链接】starrocksThe worlds 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考