通过 AuditLoader 管理 StarRocks 中的审计日志
本文档介绍如何通过插件 AuditLoader 在表中管理 StarRocks 审计日志。
StarRocks 将其审计日志存储在本地文件 **fe/log/fe.audit.log** 中，而不是内部数据库中。插件 AuditLoader 允许您直接在集群中管理审计日志。安装后，AuditLoader 会从文件中读取日志，并通过 HTTP PUT 将其加载到 StarRocks 中。然后，您可以使用 SQL 语句查询 StarRocks 中的审计日志。
创建表以存储审计日志
在 StarRocks 集群中创建数据库和表来存储其审计日志。有关详细说明，请参见 CREATE DATABASE 和 CREATE TABLE。
由于不同 StarRocks 版本的审计日志字段有所不同，因此务必遵循以下建议，以避免升级期间的兼容性问题
注意
- 所有新字段都应标记为
NULL。- 不应重命名字段，因为用户可能依赖它们。
- 仅应将向后兼容的更改应用于字段类型，例如
VARCHAR(32)->VARCHAR(64)，以避免插入期间出现错误。AuditEvent字段仅按名称解析。表中的列顺序无关紧要，用户可以随时更改。- 表中不存在的
AuditEvent字段将被忽略，因此用户可以删除不需要的列。
CREATE DATABASE starrocks_audit_db__;
CREATE TABLE starrocks_audit_db__.starrocks_audit_tbl__ (
`queryId` VARCHAR(36) COMMENT "Unique query ID",
`timestamp` DATETIME NOT NULL COMMENT "Query start time",
`queryType` VARCHAR(12) COMMENT "Query type (query, slow_query, connection)",
`clientIp` STRING COMMENT "Client IP address and optional port number",
`user` STRING COMMENT "User who initiates the query",
`authorizedUser` STRING COMMENT "user_identity in MySQL format ('user'@'host', 'user'@'%')",
`resourceGroup` STRING COMMENT "Resource group name",
`catalog` STRING COMMENT "Catalog name",
`db` STRING COMMENT "Database that the query scans",
`state` VARCHAR(8) COMMENT "Query state (EOF, ERR, OK)",
`errorCode` STRING COMMENT "Error code",
`queryTime` BIGINT COMMENT "Query time in milliseconds",
`scanBytes` BIGINT COMMENT "Size of the scanned data in bytes",
`scanRows` BIGINT COMMENT "Row count of the scanned data",
`returnRows` BIGINT COMMENT "Row count of the result",
`cpuCostNs` BIGINT COMMENT "CPU resources consumption time, in nanoseconds",
`memCostBytes` BIGINT COMMENT "Memory cost in bytes",
`stmtId` BIGINT COMMENT "Incremental SQL statement ID",
`isQuery` TINYINT COMMENT "If the SQL is a query (0 and 1)",
`feIp` STRING COMMENT "IP address of FE that executes the SQL",
`stmt` VARCHAR(1048576) COMMENT "Original SQL statement. Since AuditLoader v3.0.1",
`digest` VARCHAR(32) COMMENT "Slow SQL fingerprint, calculated only if enable_compute_all_query_digest=true. Since AuditLoader v3.0.1",
`planCpuCosts` DOUBLE COMMENT "CPU resources consumption time for planning in nanoseconds. Since AuditLoader v3.0.1",
`planMemCosts` DOUBLE COMMENT "Memory cost for planning in bytes. Since AuditLoader v3.0.1",
`pendingTimeMs` BIGINT COMMENT "Time spent in query queue if query_queue_enable=true, in milliseconds. Since AuditLoader v4.2.0",
`candidateMvs` STRING COMMENT "Names of Materialized Views marked as candidates, separated with comma. Since StarRocks v3.2.0 and AuditLoader v4.2.0",
`hitMVs` STRING COMMENT "Names of Materialized Views rewritten by query optimizer, separated with comma. Since StarRocks v3.2.0 and AuditLoader v4.2.0",
`warehouse` STRING COMMENT "Warehouse name. Since StarRocks v3.3.0 and AuditLoader v4.2.1"
) 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"
);
starrocks_audit_tbl__ 是使用动态分区创建的。默认情况下，第一个动态分区在表创建后 10 分钟创建。然后可以将审计日志加载到表中。您可以使用以下语句检查表中的分区
SHOW PARTITIONS FROM starrocks_audit_db__.starrocks_audit_tbl__;
创建分区后，您可以继续执行下一步。
下载并配置 AuditLoader
-
下载 AuditLoader 安装包。该软件包与所有可用的 StarRocks 版本兼容。
-
解压缩安装包。
unzip auditloader.zip以下文件将被解压缩
- **auditloader.jar**：AuditLoader 的 JAR 文件。
- **plugin.properties**：AuditLoader 的属性文件。您无需修改此文件。
- **plugin.conf**：AuditLoader 的配置文件。在大多数情况下，您只需要修改文件中的
user和password字段。
-
修改 **plugin.conf** 以配置 AuditLoader。您必须配置以下项目以确保 AuditLoader 可以正常工作
frontend_host_port：FE IP 地址和 HTTP 端口，格式为<fe_ip>:<fe_http_port>。建议将其设置为默认值127.0.0.1:8030。StarRocks 中的每个 FE 独立管理其自己的审计日志，并且在安装插件后，每个 FE 将启动其自己的后台线程以获取和保存审计日志，并通过 Stream Load 写入。frontend_host_port配置项用于为插件的后台 Stream Load 任务提供 HTTP 协议的 IP 和端口，此参数不支持多个值。参数的 IP 部分可以使用集群中任何 FE 的 IP，但不建议这样做，因为如果相应的 FE 崩溃，其他 FE 的后台审计日志写入任务也会由于通信失败而失败。建议将其设置为默认值127.0.0.1:8030，以便每个 FE 使用自己的 HTTP 端口进行通信，从而避免在其他 FE 发生异常时对通信产生影响（所有写入任务最终将转发到 FE Leader 节点执行）。database：您创建的用于托管审计日志的数据库的名称。table：您创建的用于托管审计日志的表的名称。user：您的集群用户名。您必须具有将数据 (LOAD_PRIV) 加载到表中的权限。password：您的用户密码。secret_key：用于加密密码的密钥（字符串，长度不得超过 16 个字节）。如果未设置此参数，则表示 **plugin.conf** 中的密码不会被加密，您只需要在password中指定明文密码。如果指定了此参数，则表示密码已由此密钥加密，您需要在password中指定加密的字符串。加密的密码可以使用 StarRocks 中的AES_ENCRYPT函数生成：SELECT TO_BASE64(AES_ENCRYPT('password','secret_key'));。enable_compute_all_query_digest：是否为所有查询生成 Hash SQL 指纹（StarRocks 默认情况下仅为慢查询启用 SQL 指纹）。请注意，插件中的指纹计算与 FE 的指纹计算不同，它将 规范化 SQL 语句，而插件不会。如果启用此功能，指纹计算将消耗额外的计算资源。filter：审计日志加载的过滤条件。此参数基于 Stream Load 中的 WHERE 参数，即-H “where: <condition>”，默认为空字符串。示例：filter=isQuery=1 and clientIp like '127.0.0.1%' and user='root'。
-
将文件压缩回一个包。
zip -q -m -r auditloader.zip auditloader.jar plugin.conf plugin.properties -
将软件包分发到所有托管 FE 节点的计算机。确保所有软件包都存储在相同的路径中。否则，安装将失败。记住在分发软件包后复制软件包的绝对路径。
注意
您还可以将 **auditloader.zip** 分发到所有 FE 都可以访问的 HTTP 服务（例如，
httpd或nginx），并使用网络安装它。请注意，在这两种情况下，**auditloader.zip** 都需要在执行安装后保留在路径中，并且安装后不应删除源文件。
安装 AuditLoader
执行以下语句以及您复制的路径以在 StarRocks 中安装 AuditLoader 作为插件
INSTALL PLUGIN FROM "<absolute_path_to_package>";
从本地包安装的示例
INSTALL PLUGIN FROM "<absolute_path_to_package>";
如果要通过网络路径安装插件，则需要在 INSTALL 语句的属性中提供软件包的 md5。
示例
INSTALL PLUGIN FROM "http://xx.xx.xxx.xxx/extra/auditloader.zip" PROPERTIES("md5sum" = "3975F7B880C9490FE95F42E2B2A28E2D");
有关详细说明，请参见 INSTALL PLUGIN。
验证安装并查询审计日志
-
您可以通过 SHOW PLUGINS 检查安装是否成功。
在以下示例中，插件
AuditLoader的Status为INSTALLED，表示安装成功。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 2.5+. Load audit log to starrocks, and user can view the statistic of queries
Version: 4.2.1
JavaVersion: 1.8.0
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) -
执行一些随机 SQL 以生成审计日志，并等待 60 秒（或您在配置 AuditLoader 时在项目
max_batch_interval_sec中指定的时间），以允许 AuditLoader 将审计日志加载到 StarRocks 中。 -
通过查询表检查审计日志。
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
warehouse: default_warehouse
1 row in set (0.01 sec)
问题排查
如果在创建动态分区和安装插件后没有将审计日志加载到表中，则可以检查 **plugin.conf** 是否配置正确。要修改它，您必须首先卸载插件
UNINSTALL PLUGIN AuditLoader;
AuditLoader 的日志打印在每个 FE 的 **fe.log** 中，您可以通过在 **fe.log** 中搜索关键字 audit 来检索它们。在所有配置都正确设置后，您可以按照上述步骤再次安装 AuditLoader。