SpacetimeDB 模块日志指南从 console/log 写入到 spacetime logs 查看与过滤【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB本文围绕 SpacetimeDB 模块Module日志体系展开如何在 TypeScript、C#、Rust、C 四种服务端语言中从 reducer 写入日志如何使用spacetime logs命令查看、实时跟踪并按级别过滤日志以及日志的存储、格式与安全边界。读完本文你将能在自己的 SpacetimeDB 模块中快速落地一套规范、可排查、可监控的日志方案。日志体系概览SpacetimeDB 为模块提供了一套内建的日志能力用于调试与监控模块运行状态。需要明确的第一条边界是日志对数据库所有者database owner私有客户端client无法看到。也就是说日志不是广播给所有订阅者的数据而是运维视角的诊断信息。从实现上看日志贯穿了「模块运行时 → 数据库日志记录器 → CLI 读取」整条链路模块侧不同语言通过各自的日志 APITypeScript 的console、C# 的Log类、Rust 的logcrate、C 的LOG_*宏发出日志宿主侧模块宿主host将日志记录序列化后写入DatabaseLogger。其存储后端支持按天滚动的文件日志详见 crates/core/src/database_logger.rs 中的FileLoggermaybe_rotate会在跨天时自动轮转日志文件查看侧spacetime logs子命令通过 HTTP 接口/v1/database/{identity}/logs读取日志流并格式化输出实现在 crates/cli/src/subcommands/logs.rs。说明--since等时间范围过滤在原文档示例中出现但当前仓库的spacetime logs子命令实际提供的过滤参数为--level与--level-exact本文以仓库源码为准展开。在不同语言中写入日志日志写入 API 因模块服务端语言而异但语义统一都对应 error / warn / info / debug / trace 等标准级别。TypeScript直接使用 consoleTypeScript 模块不需要引入额外日志库直接使用标准consoleAPI 即可SpacetimeDB 会自动将这些标准调用路由到内部日志系统。import { schema, t } from spacetimedb/server; const spacetimedb schema({ /* tables */ }); export default spacetimedb; export const processData spacetimedb.reducer({ value: t.u32() }, (ctx, { value }) { console.log(Processing data with value: ${value}); if (value 100) { console.warn(Value ${value} exceeds threshold); } if (value 0) { console.error(Invalid value: 0); throw new Error(Value cannot be zero); } console.debug(Debug information: ctx.sender ${ctx.sender}); });可用的 console 方法及对应级别console 方法语义console.error()错误消息console.warn()警告消息console.log()信息消息console.debug()调试消息从实现看TypeScript 宿主通过模块 ABI 中的console_log(level, message)系统调用把 console 输出接入日志系统相关代码见 crates/core/src/host/v8/syscall/common.rsconsole_log、console_timer_start/console_timer_end。后者表明宿主还支持用计时器把某段代码的执行耗时写入模块日志可用于性能排查。C#使用 SpacetimeDB.Log 类C# 模块使用SpacetimeDB.Log静态类写入日志using SpacetimeDB; public static partial class Module { [SpacetimeDB.Reducer] public static void ProcessData(ReducerContext ctx, uint value) { Log.Info($Processing data with value: {value}); if (value 100) { Log.Warn($Value {value} exceeds threshold); } if (value 0) { Log.Error(Invalid value: 0); throw new ArgumentException(Value cannot be zero); } Log.Debug($Debug information: ctx.Sender {ctx.Sender}); } }可用的 Log 方法及对应级别Log 方法语义Log.Error()错误消息Log.Warn()警告消息Log.Info()信息消息Log.Debug()调试消息Log.Trace()跟踪消息Rust使用 log crateRust 模块直接使用业界标准的logcrate 宏模块运行时已为其配置好日志实现use spacetimedb::{reducer, ReducerContext}; #[reducer] pub fn process_data(ctx: ReducerContext, value: u32) - Result(), String { log::info!(Processing data with value: {}, value); if value 100 { log::warn!(Value {} exceeds threshold, value); } if value 0 { log::error!(Invalid value: 0); return Err(Value cannot be zero.to_string()); } log::debug!(Debug information: ctx.sender {:?}, ctx.sender()); Ok(()) }可用的 log 宏log 宏语义log::error!()错误消息log::warn!()警告消息log::info!()信息消息log::debug!()调试消息log::trace!()跟踪消息C使用 LOG_* 宏C 模块通过LOG_*宏写入日志注意C 模块版本有一定前提具体请参见模块版本说明using namespace SpacetimeDB; SPACETIMEDB_REDUCER(process_data, ReducerContext ctx, uint32_t value) { LOG_INFO(Processing data with value: std::to_string(value)); if (value 100) { LOG_WARN(Value std::to_string(value) exceeds threshold); } if (value 0) { LOG_ERROR(Invalid value: 0); return Err(Value cannot be zero); } LOG_DEBUG(Debug information: ctx.sender ctx.sender().to_string()); return Ok(); }可用的 LOG 宏宏语义LOG_ERROR()错误消息LOG_WARN()警告消息LOG_INFO()信息消息LOG_DEBUG()调试消息LOG_PANIC()/LOG_FATAL()致命错误会终止 reducer 执行日志级别语义各语言的日志 API 最终都映射到统一级别。结合 crates/cli/src/subcommands/logs.rs 中的LogLevel::severity()从低到高的严重程度为Traceseverity 0非常详细的诊断信息通常在生产环境关闭Debugseverity 1开发期使用的详细诊断信息Infoseverity 2重要的应用事件用户操作、状态变更Warnseverity 3可能有问题但不阻断执行的情况Errorseverity 4真正导致操作无法完成错误Panicseverity 5致命错误如 Rust panic / CLOG_PANIC会终止 reducer。查看与过滤日志spacetime logs 命令查看数据库日志使用spacetime logs子命令。其 CLI 定义见 crates/cli/src/subcommands/logs.rs以下是完整参数表参数简写说明DATABASE_NAME—数据库名称或 identity--server SERVER—托管数据库的服务器昵称、主机名或 URL--num-lines N-n从日志开头打印 N 行不指定则返回全部行--follow-f类似tail -f持续流式输出新日志--format text\|json—输出格式默认textjson输出每条记录的原始 JSON--level LEVEL-l最低显示级别trace/debug/info/warn/error/panic--level-exact—与--level组合只显示恰好等于该级别的日志--no-config—忽略spacetime.json配置--yes/-y—跳过确认提示基础用法# 查看某个数据库的全部日志 spacetime logs DATABASE_NAME实时跟踪日志spacetime logs --follow DATABASE_NAME与tail -f语义一致日志到达文件末尾后不停止而是继续等待新数据追加。从实现看--follow模式下若未显式指定--num-linesCLI 会自动将行数设为 10避免从最早的日志开始回放见 crates/cli/src/subcommands/logs.rs 中follow num_lines.is_none()的处理逻辑。按级别过滤# 只看 error 及以上 spacetime logs --level error DATABASE_NAME # 只看 warn 及以上 spacetime logs --level warn DATABASE_NAME # 只显示恰好是 warn 级别的日志配合 --level-exact spacetime logs --level warn --level-exact DATABASE_NAME过滤逻辑在should_display()中实现未指定--level时全部显示指定后默认显示「该级别及以上」而--level-exact会改为「恰好等于该级别」。注意过滤发生在 CLI 侧对--format json输出同样生效。文本输出的字段构成text格式下每条日志会按记录元数据渲染为「时间戳 级别 函数名 文件名:行号 消息」的结构字段存在时并带有终端配色error 红色、warn 黄色、info 蓝色、debug/trace 置灰、panic 红色加粗。若记录带有 backtrace 帧还会以in module :: function的形式逐帧打印堆栈。JSON 输出的记录结构使用--format json可以拿到未经格式化的原始记录便于程序化消费。每条记录是 JSON 行字段对应 crates/core/src/database_logger.rs 中Record结构tsUTC 时间戳微秒精度leveltrace/debug/info/warn/error/panictarget日志目标filename与line_number产生日志的源文件与行号function产生日志的函数名message日志消息正文trace可选的 backtrace 帧列表module_name、func_name。日志的后端存储日志由DatabaseLogger统一管理。核心存储后端是FileLogger见 crates/core/src/database_logger.rs记录以追加方式写入文件按天滚动跨天时切换到新日期文件支持tail/tail_stream读取文件尾部指定行数并流式输出。这解释了spacetime logs能返回「全部行」或「最近 N 行」的能力来源。系统注入的日志如模块生命周期事件使用__spacetimedb__哨兵值标记 target/filename/functionCLI 渲染时会跳过这些哨兵字段。日志最佳实践按语义选择合适的级别Error真正阻止操作完成的错误Warn潜在问题但不阻断执行Info重要的应用事件用户操作、状态变更Debug开发期有用的详细诊断信息Trace非常详细的诊断信息生产环境通常禁用。性能考量日志本身开销很小但过量日志会拖累性能避免在紧密循环或高频操作中写日志需要输出大段细节时优先用 debug/trace 级别生产环境可通过--level过滤从源头减少落盘压力。隐私与安全日志仅对数据库所有者可见客户端无法读取不要记录密码、认证令牌等敏感信息注意日志中可能包含的个人可识别信息PII按合规要求脱敏。结构化日志携带上下文为便于排查与后续分析日志消息应携带足够的上下文。推荐把ctx.sender、业务主键、金额等关键参数拼进消息export const transferCredits spacetimedb.reducer( { toUser: t.u64(), amount: t.u32() }, (ctx, { toUser, amount }) { console.log(Credit transfer: from${ctx.sender}, to${toUser}, amount${amount}); // ... transfer logic } );[SpacetimeDB.Reducer] public static void TransferCredits(ReducerContext ctx, ulong toUser, uint amount) { Log.Info($Credit transfer: from{ctx.Sender}, to{toUser}, amount{amount}); // ... transfer logic }Rust 侧可借助logcrate 直接写出带键值语义的结构化格式便于日志分析工具解析use spacetimedb::log; #[reducer] pub fn transfer_credits(ctx: ReducerContext, to_user: u64, amount: u32) - Result(), String { log::info!( Credit transfer: from{:?}, to{}, amount{}, ctx.sender(), to_user, amount ); // ... transfer logic Ok(()) }using namespace SpacetimeDB; SPACETIMEDB_REDUCER(transfer_credits, ReducerContext ctx, uint64_t to_user, uint32_t amount) { LOG_INFO(Credit transfer: from ctx.sender().to_string() , to std::to_string(to_user) , amount std::to_string(amount)); // ... transfer logic return Ok(); }相关参考学习 reducer 中的 错误处理完整的spacetime logs参数说明见 CLI 参考日志记录的底层数据结构与存储实现见 crates/core/src/database_logger.rsspacetime logs的完整 CLI 实现见 crates/cli/src/subcommands/logs.rs宿主侧把模块 console 输出接入日志系统的实现见 crates/core/src/host/v8/syscall/common.rs。在此基础上可以为生产环境的数据库进一步设置监控与告警例如定时执行spacetime logs --level error抓取错误、配合 JSON 输出接入日志采集系统做聚合分析。【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考