DuckDB 实现了一种日志记录机制，为用户提供有关查询执行、性能指标和系统事件等事件的详细信息。

基础知识

可以使用特殊函数 enable_logging 启用或禁用 DuckDB 日志记录机制。日志存储在名为 duckdb_logs 的特殊视图中，可以像查询标准表一样对其进行查询。

示例

CALL enable_logging();
-- Run some queries...
SELECT * FROM duckdb_logs;

要禁用日志记录，请运行

CALL disable_logging();

要清除当前日志，请运行

CALL truncate_duckdb_logs();

日志级别

DuckDB 支持不同的日志级别，用于控制日志的详细程度

• ERROR：仅记录错误消息
• WARN：记录警告和错误
• INFO：记录常规信息、警告和错误（默认）
• DEBUG：记录详细的调试信息
• TRACE：记录非常详细的跟踪信息

可以使用以下命令设置日志级别

CALL enable_logging(level = 'debug');

日志类型

在 DuckDB 中，日志消息可以关联一个日志类型。日志类型主要支持以下两点

• 对日志消息生成的细粒度控制
• 对结构化日志记录的支持

特定于日志记录的类型

要仅记录特定类型的消息

CALL enable_logging('HTTP');

上述函数将自动设置正确的日志级别，并将 HTTP 类型添加到 enabled_log_types 设置中。这确保只有“HTTP”类型的日志消息会被写入日志。

要启用多种日志类型，只需传入

CALL enable_logging(['HTTP', 'QueryLog']);

结构化日志记录

某些日志类型（如 HTTP）将关联一个消息模式。要让 DuckDB 自动解析该消息，请使用 duckdb_logs_parsed() 宏。例如

SELECT request.headers FROM duckdb_logs_parsed('HTTP');

要查看每种结构化日志类型的模式，只需运行

DESCRIBE FROM duckdb_logs_parsed('HTTP');

可用日志类型列表

这是一个 DuckDB 中可用日志类型的列表（非详尽）。

日志存储

默认情况下，DuckDB 会记录到内存中的日志存储（memory）。DuckDB 支持不同类型的日志存储。目前，核心 DuckDB 中实现了以下日志存储类型。

请注意，duckdb_logs 视图会自动更新以指向当前活动的日志存储。这意味着切换日志存储可能会影响 duckdb_logs 函数返回的内容。

记录到 stdout

CALL enable_logging(storage = 'stdout');

记录到文件

CALL enable_logging(storage = 'file', storage_config = {'path': 'path/to/store/logs'});

或使用等效的简写

CALL enable_logging(storage_path = 'path/to/store/logs');

高级用法

规范化与非规范化日志记录

DuckDB 的日志存储可以通过两种方式进行记录：规范化或非规范化。

在非规范化日志记录中，日志上下文信息直接附加到每个日志条目；而在规范化日志记录中，日志条目是分开存储的，并使用 context_ids 引用上下文信息。

对于文件存储，您可以通过提供以 .csv 结尾的路径（用于规范化）或不以 .csv 结尾的路径（用于非规范化）来在规范化和非规范化之间切换。对于文件日志记录，通常建议使用非规范化，因为这可以提高性能并减小日志的总大小。要配置 file 日志存储的规范化

-- normalized: creates `/tmp/duckdb_log_contexts.csv` and `/tmp/duckdb_log_entries.csv`
CALL enable_logging(storage_path = '/tmp');
-- denormalized: creates `/tmp/logs.csv`
CALL enable_logging(storage_path = '/tmp/logs.csv');

请注意，规范化和非规范化之间的差异通常通过 'duckdb_logs' 函数对用户隐藏，该函数会自动将规范化表连接成一个统一的结果。举例来说，上述两种配置都可以使用 FROM duckdb_logs; 进行查询，并产生相同的结果。

缓冲区大小

DuckDB 中的日志存储实现了缓冲机制以优化日志记录性能。这种实现会在消息记录和存储写入之间引入潜在的延迟。这种延迟可能会掩盖实际的消息写入时间，这在调试崩溃时尤为棘手，因为在崩溃前瞬间生成的消息可能尚未写入。为了解决这个问题，可以按如下方式配置缓冲区大小

CALL enable_logging(storage_config = {'buffer_size': 0});

或使用等效的简写

CALL enable_logging(storage_buffer_size = 0);

请注意，不同日志存储的默认缓冲区大小有所不同

例如，如果您想提高 stdout 日志记录的性能，只需启用缓冲即可大大（>10倍）加速日志记录

CALL enable_logging(storage = 'stdout', storage_buffer_size = 2048);

或者假设您正在调试 DuckDB 中的崩溃，并且想使用 file 记录器来了解发生了什么：只需通过以下方式禁用缓冲

CALL enable_logging(storage_path = '/tmp/mylogs', storage_buffer_size = 2048);

语法糖

DuckDB 包含一些语法糖，使常见路径的使用更加容易。例如，以下语句是等效的

-- regular invocation 
CALL enable_logging(storage = 'file', storage_config = {'path': 'path/to/store/logs'});
-- using shorthand for common path storage config param 
CALL enable_logging(storage = 'file', storage_path = 'path/to/store/logs');
-- omitting `storage = 'file'` -> is implied from presence of `storage_config`
CALL enable_logging(storage_config = {'path': 'path/to/store/logs'});