如何配置Cassandra日志查看CQL执行的Java底层过程并追踪语法异常

一、是否存在底层Java执行日志？如何配置？ #

Cassandra支持通过调整日志级别，查看CQL语句从执行到响应全过程的底层Java执行细节，核心是修改Logback日志配置（Cassandra默认使用Logback）：

1. 定位日志配置文件
   默认路径为<Cassandra安装目录>/conf/logback.xml。

2. 开启关键组件的DEBUG/TRACE日志
   根据需要追踪的环节，添加或修改对应包的日志级别：

   • 若要追踪CQL解析、校验流程，重点开启org.apache.cassandra.cql3包的DEBUG日志：

     <logger name="org.apache.cassandra.cql3" level="DEBUG"/>
     

   • 若要追踪客户端请求处理链路（包括权限校验、语句执行流程），开启org.apache.cassandra.service.ClientState和org.apache.cassandra.transport的DEBUG日志：

     <logger name="org.apache.cassandra.service.ClientState" level="DEBUG"/>
     <logger name="org.apache.cassandra.transport" level="DEBUG"/>
     

   • 若需要最细粒度的底层执行细节（如存储引擎交互），可将org.apache.cassandra根包级别设为TRACE，但会产生大量日志，建议仅临时启用。

3. 生效配置
   保存配置后，重启Cassandra服务（若logback.xml中配置了<configuration scan="true">，则无需重启，等待1分钟左右自动刷新）。

4. 查看日志
   日志默认输出到<Cassandra安装目录>/logs/system.log，可直接查看或用日志分析工具过滤。

二、全查询日志（FQL）问题及SyntaxException追踪 #

1. FQL仅显示INFO级语句和系统查询的解决方法 #

全查询日志默认会记录所有用户及系统发起的CQL语句，若需过滤系统查询：

• 实时过滤：使用fqltool时添加过滤参数：

  fqltool filter --exclude-system /path/to/full_query.log
  

• 配置层面过滤：修改cassandra.yaml中的full_query_logging_options：

  full_query_logging_options:
    exclude_cql_types: ["SYSTEM"]
    # 或指定仅记录目标键空间
    include_keyspaces: ["your_keyspace"]
  

  修改后需重启Cassandra生效。

2. 追踪SyntaxException的Java类 #

SyntaxException是在CQL语句解析阶段抛出的，此时请求尚未进入全查询日志的记录流程，因此无法通过FQL追踪。需通过以下方式获取异常类信息：

• 确保已开启org.apache.cassandra.cql3包的DEBUG日志（参考第一部分配置）。
• 重新执行触发异常的GRANT语句，此时system.log中会输出完整的异常堆栈信息，其中包含抛出异常的具体Java类（通常为org.apache.cassandra.cql3.parser.CqlParser或其关联类）。

内容的提问来源于stack exchange，提问作者Aleix Rué