Rerun TextLog 原型详解字段模型、组件编码与跨语言日志集成【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun本文围绕 Rerun 的TextLog原型archetype展开系统讲解其由text/level/color三个组件构成的数据模型、各组件的编码方式与 Rust 源码实现细节并完整给出 Rust、Python、C 三种语言将TextLog与原生日志系统log、logging、Loguru打通的官方示例代码。读完后你将能够在自己的项目中以 Rerun 数据流方式记录结构化文本日志并通过 Rerun Viewer 的 TextLogView / DataframeView 进行查看与过滤。1. TextLog 原型是什么Rerun 官方类型参考文档docs/content/reference/types/archetypes/text_log.md对TextLog的定义是A log entry in a text log, comprised of a text body and its log level. 文本日志中的一条日志记录由文本正文及其日志级别组成。它是 Rerun 数据模型中的一个原型原型是把若干组件component按语义打包在一起的记录单元每条日志通过一条实体路径entity path如logs、logs/handler记录到数据流中。原型的完整字段构成如下字段级别组件类型说明textRequired必需Text日志正文字符串内容levelRecommended推荐TextLogLevel日志严重级别可用于 Viewer 中过滤日志消息colorOptional可选Color日志行在 Viewer 中显示时使用的颜色从源码结构看这一字段划分与 Rust 实现完全对应TextLog结构体只有text、level、color三个字段且NUM_COMPONENTS常量被显式标注为 “1 required, 1 recommended, 1 optional”共 3 个组件见 crates/store/re_sdk_types/src/archetypes/text_log.rs。TextLog可以被以下视图展示TextLogViewdocs/content/reference/types/views/text_log_view.md 中的TextLogView类型定义专门的文本日志视图支持列选择、行过滤与格式化选项DataframeView表格视图可以把日志当作数据表的一列来查询与展示。2. 字段级组件模型与编码2.1 text 字段Text 组件Text组件的定义是 “A string of text, e.g. for labels and text documents”一段文本字符串例如用于标签和文本文档。它的关键编码信息见 docs/content/reference/types/components/text.mdRerun 编码Utf8Arrow 数据类型Utf8。值得注意的是Text并不是TextLog专属组件——从该组件文档的 “Used by” 列表可以看到它同样被Arrows2D/3D、Boxes2D/3D、Points2D/3D、LineStrips2D/3D、TextDocument等大量原型用作标签或文本内容。这意味着 Rerun 在类型系统层面复用了同一个字符串组件日志正文与图形标注共享同一套 Arrow 序列化管线。2.2 level 字段TextLogLevel 组件TextLogLevel表示 “The severity level of a text log message”文本日志消息的严重级别同样是Utf8编码的 Arrow 字符串推荐取值为以下六种CRITICALERRORWARNINFODEBUGTRACE在 Rust 侧TextLogLevel是对Utf8编码的一个 newtype 包装见 crates/store/re_sdk_types/src/components/text_log_level.rs。由于底层只是 UTF-8 字符串级别值并非严格封闭枚举——C 示例中当 Loguru 的 verbosity 无法映射到已知级别时直接以rerun::TextLogLevel(std::to_string(message.verbosity))构造自定义级别这也是该组件 “Recommended” 而非严格枚举的语义体现。2.3 color 字段color是可选的Color组件用于指定该日志行在 Rerun Viewer 中的显示颜色。它使TextLog能够以颜色编码承载额外的语义例如区分不同来源、不同子系统的日志。3. Rust 实现细节从 def 定义到生成代码TextLog的 Rust API 是由类型构建器自动生成的文件头注释明确标注其基于crates/build/re_type_definitions/rerun/archetypes/text_log.def.rs即 crates/build/re_type_definitions/rerun/archetypes/text_log.def.rs由代码生成器产出 crates/store/re_sdk_types/src/archetypes/text_log.rs。阅读这份生成代码可以看清 Rerun 原型体系的核心机制1每个字段都带组件描述符。生成代码为三个字段分别定义了ComponentDescriptor如 descriptor_text()其中携带了完整的三元组信息archetype:rerun.archetypes.TextLogcomponent:TextLog:textcomponent_type:rerun.components.Text描述符是数据在 Arrow 列存中往返序列化时的“身份证”保证反序列化时能按名称精确找回对应列见from_arrow_components的实现text_log.rs#L188-L206。2字段以 Option 承载 Arrow 批。结构体字段类型为OptionSerializedComponentBatchNone表示该组件未设置Some内是一个带描述符的 Arrow 数组批。这使同一结构体既能表达单条记录with_text/with_level/with_color也能表达整列批量数据with_many_*系列方法。3构造与链式更新 API。生成代码提供了完整的使用面TextLog::new(text)以正文构造level与color初始为Nonetext_log.rs#L229-L238.with_level(TextLogLevel::TRACE)、.with_color(...)链式补全推荐/可选字段.with_many_text(...)等把多个组件打包进单个批配合columns()使用.columns(lengths)/.columns_of_unit_batches()将组件批按长度切分为SerializedComponentColumn列供RecordingStream::send_columns直接发送列式数据text_log.rs#L266-L311。4可视化注册。VisualizableArchetypetrait 实现将TextLog注册到名为TextLog的可视化器text_log.rs#L222-L227这是它能够在 Viewer 中被自动渲染的底层依据。4. 实战示例与原生日志系统集成官方类型文档给出的示例名为text_log_integration其核心思路是两种用法并存直接记录一条TextLog以及把宿主语言的整个日志框架接入 Rerun。仓库中提供 Rust、Python、C 三版实现可分别作为对应语言项目的接入模板。4.1 Rust 版对接log宏与RUST_LOG来源docs/snippets/all/archetypes/text_log_integration.rsuse rerun::external::log; fn main() - Result(), Boxdyn std::error::Error { let rec rerun::RecordingStreamBuilder::new( rerun_example_text_log_integration, ) .spawn()?; // 用法一直接记录一条 TextLog rec.log( logs, rerun::TextLog::new(this entry has loglevel TRACE) .with_level(rerun::TextLogLevel::TRACE), )?; // 用法二把 Rerun 挂到标准 logging 接口上 rerun::Logger::new(rec.clone()) // recording streams are ref-counted .with_path_prefix(logs/handler) // 同时支持标准的 RUST_LOG 环境变量 .with_filter(rerun::default_log_filter()) .init()?; log::info!( This INFO log got added through the standard logging interface ); log::logger().flush(); Ok(()) }要点解析第一条日志走rec.log(logs, TextLog)手工指定TRACE级别第二条日志则完全不感知 Rerun 的存在——rerun::Logger把RecordingStream引用计数可clone()共享包装成全局loghandler之后所有log::info!等宏调用都会落到logs/handler实体下with_filter(rerun::default_log_filter())复用了标准的RUST_LOG过滤语义级别过滤在数据发出前完成而非全部写入再在 Viewer 里筛。4.2 Python 版对接logging模块来源docs/snippets/all/archetypes/text_log_integration.pyShows integration of Reruns TextLog with the native logging interface. import logging import rerun as rr rr.init(rerun_example_text_log_integration, spawnTrue) # 用法一直接记录一条 TextLog rr.log( logs, rr.TextLog(this entry has loglevel TRACE, levelrr.TextLogLevel.TRACE), ) # 用法二挂到 Python 标准 logging 的 handler 上 logging.getLogger().addHandler(rr.LoggingHandler(logs/handler)) logging.getLogger().setLevel(-1) logging.info(This INFO log got added through the standard logging interface)Python 侧的接入点是把rr.LoggingHandler附加到 root logger 上此后任何模块调用logging.info(...)产生的记录都会以TextLog形式写入logs/handler实体。4.3 C 版对接 Loguru来源docs/snippets/all/archetypes/text_log_integration.cpp/// 将 C Loguru 日志库桥接到 Rerun #include loguru.hpp #include rerun.hpp void loguru_to_rerun(void* user_data, const loguru::Message message) { // 注意rerun::RecordingStream 是线程安全的 const rerun::RecordingStream* rec reinterpret_castconst rerun::RecordingStream*(user_data); // 把 Loguru 的 Verbosity 映射为 TextLogLevel rerun::TextLogLevel level; if (message.verbosity loguru::Verbosity_FATAL) { level rerun::TextLogLevel::Critical; } else if (message.verbosity loguru::Verbosity_ERROR) { level rerun::TextLogLevel::Error; } else if (message.verbosity loguru::Verbosity_WARNING) { level rerun::TextLogLevel::Warning; } else if (message.verbosity loguru::Verbosity_INFO) { level rerun::TextLogLevel::Info; } else if (message.verbosity loguru::Verbosity_1) { level rerun::TextLogLevel::Debug; } else if (message.verbosity loguru::Verbosity_2) { level rerun::TextLogLevel::Trace; } else { level rerun::TextLogLevel(std::to_string(message.verbosity)); } rec-log( logs/handler/text_log_integration, rerun::TextLog(message.message).with_level(level) ); } int main(int argc, char* argv[]) { const auto rec rerun::RecordingStream(rerun_example_text_log_integration); rec.spawn().exit_on_failure(); // 用法一直接记录一条 rec.log( logs, rerun::TextLog(this entry has loglevel TRACE) .with_level(rerun::TextLogLevel::Trace) ); // 用法二注册 Loguru 回调仅 INFO 及以上 loguru::add_callback( rerun, loguru_to_rerun, const_castvoid*(reinterpret_castconst void*(rec)), loguru::Verbosity_INFO ); LOG_F(INFO, This INFO log got added through the standard logging interface); // 必须在 rec 析构之前移除回调 loguru::remove_callback(rerun); }C 版额外展示了跨语言级别映射的完整分支FATAL→Critical、ERROR→Error、WARNING→Warning、INFO→Info、_1→Debug、_2→Trace并提示了两个工程细节RecordingStream线程安全可直接在回调中调用回调必须在流对象析构前remove_callback避免悬垂指针。5. 在 Viewer 中查看TextLogView 与 DataframeViewTextLog记录完成后展示侧由蓝图blueprint视图接管。参考文档 TextLogView 类型定义 说明该视图当前标记为不稳定unstable属性结构为columns要显示的列其中timeline_columns指定显示哪些时间线列text_log_columns指定日志数据列rows对要显示的行进行过滤format_options文本日志视图的格式化选项。配合TextLogLevel字段TextLogView 可以按级别过滤日志消息——这正是原型文档中 “This can be used to filter the log messages in the Rerun Viewer” 一句的落地机制。若希望以表格方式做进一步查询例如把日志与机器人其他数据流按时间对齐则可将同一实体交给 DataframeView 展示。6. 小结与延伸阅读TextLog是 Rerun 数据模型中一个典型的“小而完整”的原型一个必需的Text正文、一个推荐的TextLogLevel级别和一个可选的Color三者通过统一的 ArrowUtf8编码进入同一套存储与查询管线并在展示侧由 TextLogView 与 DataframeView 消费。其设计价值在于日志不再是散落在终端的瞬态输出而是成为带时间轴、可过滤、可与其他多模态机器人数据共同查询的一等数据。如需继续深入当前仓库建议按以下路径阅读原型文档docs/content/reference/types/archetypes/text_log.md组件文档Text、TextLogLevel类型定义源crates/build/re_type_definitions/rerun/archetypes/text_log.def.rs生成代码的上游Rust 实现crates/store/re_sdk_types/src/archetypes/text_log.rs、crates/store/re_sdk_types/src/components/text_log_level.rs三语言官方示例Rust、Python、C。【免费下载链接】rerunVisualize, query, and stream to train on multimodal robotics data.项目地址: https://gitcode.com/GitHub_Trending/re/rerun创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考