Apache Cassandra 全查询日志(FQL)功能详解与实战指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00929/article/details/148418988

Apache Cassandra 全查询日志(FQL)功能详解与实战指南

cassandra Cassandra是一个分布式的NoSQL数据库，主要用于海量数据的存储和访问。它的特点是高可用、可扩展性强、易于部署等。适用于海量数据存储和访问场景。项目地址: https://gitcode.com/gh_mirrors/cassa/cassandra

一、全查询日志(FQL)概述

Apache Cassandra 4.0引入的全查询日志(Full Query Logging, FQL)是一个高性能的实时查询日志功能，专为生产环境设计。它通过异步写入和资源限制机制，在保证系统稳定性的同时，完整记录所有CQL查询操作。

核心特性

高性能设计：采用单线程异步写入机制，对查询延迟影响极小
资源可控：
- 可配置的堆内存使用上限(加权队列)
- 可配置的磁盘空间使用上限(自动删除旧日志)
灵活的记录策略：
- 队列满时可选择阻塞或丢弃记录
- 支持多种日志滚动周期(分钟/小时/天)
丰富的工具支持：
- 通过nodetool进行启停管理
- 专用fqltool进行日志分析、回放和比较

与审计日志的区别

虽然审计日志也记录CQL请求，但FQL具有独特优势：

专门为查询回放设计，记录完整的查询上下文
包含绑定参数和查询选项等详细信息
性能开销更低，适合长期运行

二、FQL工作原理

日志记录内容

FQL会记录以下类型的查询信息：

单条CQL查询：

查询文本
查询选项(一致性级别等)
时间戳状态
执行时间(毫秒精度)

批量CQL查询：

批量中的所有查询文本
公共查询选项
时间戳状态
批量执行时间
批量类型
参数绑定值

技术实现

底层存储：基于Chronicle-Queue实现高性能二进制日志
写入流程：
- 生产者线程将记录放入加权队列
- 单消费者线程异步写入磁盘
- 队列满时根据配置决定阻塞或丢弃
日志滚动：按配置周期自动滚动日志文件
资源回收：自动删除旧日志文件以控制磁盘使用

三、FQL配置详解

通过cassandra.yaml配置

full_query_logging_options:
   log_dir: /var/log/cassandra/fql  # 日志目录(必须)
   roll_cycle: HOURLY              # 滚动周期(HOURLY/MINUTELY/DAILY)
   block: true                     # 队列满时是否阻塞
   max_queue_weight: 268435456     # 队列最大权重(默认256MB)
   max_log_size: 17179869184       # 最大日志大小(默认16GB)
   archive_command: /path/to/script.sh %path  # 归档脚本
   max_archive_retries: 10         # 归档重试次数

关键参数说明

log_dir：必须指定一个具有读写权限的目录
roll_cycle：根据业务需求选择适当的滚动频率
block：生产环境建议设为true避免数据丢失
max_queue_weight：根据节点负载调整，避免内存压力
max_log_size：根据磁盘空间和保留需求设置

四、FQL操作指南

启用FQL

nodetool enablefullquerylog --path /path/to/logs \
  --roll-cycle HOURLY \
  --max-log-size 32G \
  --blocking

停用与重置

# 停止日志记录(保留现有日志)
nodetool disablefullquerylog

# 停止并删除所有日志(谨慎使用)
nodetool resetfullquerylog

五、fqltool使用实战

日志查看

fqltool dump /path/to/logs

输出示例：

Type: single-query
Query start time: 1630000000000
Query: SELECT * FROM users WHERE id=?
Values: [1001]

查询回放

fqltool replay --target 10.0.0.1 \
  --results /path/to/results \
  /path/to/logs

结果比较

fqltool compare --queries /path/to/stored_queries \
  /path/to/result1 /path/to/result2

六、最佳实践

生产环境建议：
- 设置合理的max_log_size防止磁盘写满
- 使用archive_command将日志归档到专用存储
- 监控日志目录的磁盘使用情况
性能测试建议：
- 在测试环境评估FQL对工作负载的影响
- 根据实际负载调整max_queue_weight
故障排查技巧：
- 使用fqltool dump快速检查查询模式
- 通过回放功能重现生产环境问题