Mojo 项目 Support 日志库实战指南从 C/Mojo 接口到异步日志与 JSON 结构化输出【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读Support/docs/Logging.md及其背后源码Support/include/Support/Log.h、Support/lib/Log.cpp共同构成了 Mojo 仓库中面向全栈各层编译器、运行时、工具链的统一日志基础设施。本文基于该文档与仓库源码系统讲解其 C/Mojo 双语言接口、五级日志宏、结构化键值记录、作用域计时、环境变量配置、异步无锁落盘机制以及 NDJSON 输出格式帮助你直接上手在 Mojo 或 C 组件中接入这套日志库并理解其日志绝不停顿被观察的工作这一核心设计取舍。一、日志库定位与设计目标该库用于从技术栈的任何一层compiler、runtime、tooling 等向文件或 stdout输出日志消息每条消息都携带时间戳与严重级别。其接口统一采用一个格式化字符串 一组参数的调用形态格式化语法基于fmt与std::format类似。从 Support/include/Support/Log.h 的源码注释可以看到三个按优先级排序的设计目标用尽可能少的周期完成日志记录性能第一记录后尽快输出消息可靠地输出所有消息。这三个目标有明确的取舍顺序最典型的表现就是当生产者速率超过消费者吞吐时新记录会被直接丢弃而不是阻塞调用方见下文异步日志与丢弃一节。这意味着该库本质上是面向生产环境、零阻塞语义的日志通道而非调试期全量保真工具。二、快速上手stdout 与文件双通道日志默认输出到 stdoutMODULAR_LOG_STDOUT未设置或为true时。若同时设置了MODULAR_LOG_FILE指向一个合法路径则输出同时写入文件两条通道相互正交可以只开其一、全开或全关。# 仅输出到 stdout默认 ./your_binary # 输出到文件 MODULAR_LOG_FILE/tmp/mojo.log ./your_binary # 同时输出到 stdout 和文件 MODULAR_LOG_STDOUTtrue MODULAR_LOG_FILE/tmp/mojo.log ./your_binary # 关闭日志stdoutfalse 且不设文件路径 MODULAR_LOG_STDOUTfalse ./your_binary从源码看文件 sink 以追加写方式打开CD_OpenAlways | FA_Write | OF_Append见 Support/lib/Log.cpp因此进程重启不会清空既有日志若文件无法打开会向errs()打印诊断并在 stdout 仍启用时降级为仅 stdout 输出否则不输出任何日志。三、C 接口MLOG 宏家族与五级日志所有 C 接口都收敛到MLOG(...)这一个宏展开为M::Log::log(...)并按其参数形态自动识别用法#include Support/Log.h // 单参数以 INFO 级别输出字符串 MLOG(hello); // - hello MLOG(); // - 仅输出换行 // 两个及以上参数格式化字符串 位置参数fmt 语法 MLOG({} {}, hello, world); // - hello world MLOG({} {} {}, hello, 42, 3.14); // 若第一个参数是 LogLevel则整体左移按指定级别输出 MLOG(LogLevel::DEBUG, {} {}, hello, 42);五个便捷宏分别对应五个级别等价于显式传入级别的MLOG宏级别语义MLOG_DEBUG(...)DEBUG开发与排障用的详细调试信息MLOG_INFO(...)INFO程序正常运行的一般性信息MLOG_WARN(...)WARN潜在问题告警不影响继续执行MLOG_ERROR(...)ERROR影响功能但允许程序继续的错误MLOG_FATAL(...)FATAL严重错误记录后终止程序MLOG_FATAL的行为由宏定义直接保证见 Support/include/Support/Log.h先记录日志再flush()强制排空最后调用std::abort()。级别数值与文本前缀LogLevel枚举定义于 Support/include/Support/Log.hDEBUG0, INFO1, WARN2, ERROR3, FATAL4数值越小越详细。级别过滤是最小可写级别语义——默认级别为WARNstd::atomicLogLevel level LogLevel::WARN;即低于 WARN 的 DEBUG/INFO 默认不输出。文本前缀见 Support/lib/Log.cppDBG / INFO / WARN / ERR / FATL带颜色的终端下还分别映射为亮黑、亮青、亮黄、亮红、红色。终端着色遵循NO_COLOR环境变量约定任何值、甚至空值都会禁用颜色TERMdumb或非交互式 stdout 时也会自动关闭颜色Support/lib/Log.cpp。参数支持的类型LogArgSupport/include/Support/Log.h是一块 POD 联合体支持bool / int64 / uint64 / float / double / 字符串 / 指针。任意整型参数会自动归约到 int64/uint64任意可转换为std::string_view的类型按字符串处理不支持的参数类型会在编译期通过static_assert直接报错Unsupported log argument type.。四、结构化键值记录MLOG_KVMLOG_KV(level, key, value, ...)输出的不是格式化消息而是命名字段。它接收交替出现的键值对最多四对且键必须是字符串MLOG_KV(LogLevel::INFO, event, span_start, operation, prefill, batch_id, batchId, request_id, requestId);两种渲染形态在 JSON 模式下每一对都成为顶层字段可直接作为下游如 Datadog的索引 facet 使用非 JSON 模式下则渲染为普通前缀之后的一串keyvaluetoken[INFO] eventspan_start operationprefill batch_id42 request_ida1b2c3同一记录在MODULAR_LOG_JSON下{timestamp: 2026-03-16T12:00:00.123456Z, level: INFO, channel: default, event: span_start, operation: prefill, batch_id: 42, request_id: a1b2c3}与 MLOG 的两个关键差异级别被过滤时参数完全不求值。MLOG_KV宏先比较getLogLevel() level通过后才进入logKVSupport/include/Support/Log.h因此它安全地放在热路径上昂贵的参数在记录被过滤时零成本// summarize() 只有在 DEBUG 级别启用时才会执行 MLOG_KV(LogLevel::DEBUG, event, batch_done, stats, summarize(batch));键原样写入。请避免使用timestamp、level、channel作为键——这些是 JSON 信封envelope字段键与信封字段重名会产生重复的 JSON 键源码在 Support/lib/Log.cpp 的注释中明确警告了这一点。键长度限制与 arena 裁剪键建议控制在16 字符以内。原因在 Support/include/Support/Log.hLogArg内部为短字符串预留了 16 字节的内联缓冲区SSO≤16 字节的字符串直接内联存储、从不进入 arena超过 16 字节的字符串则被复制进记录共享的256 字节 arena而 arena 是裁剪而非扩容的——过长的键会被静默截断这等于悄悄改名的字段且两个共享前缀的长键可能被裁剪成同一个名字。值类型保持到 JSON值在 JSON 中保留原生类型数字与布尔不带引号从而可作为数值而非字符串参与下游过滤MLOG_KV(LogLevel::INFO, event, cache_lookup, hit, found, // bool - true latency_ms, elapsedMs, // double - 1.5 entries, cache.size()); // integer - 4096{timestamp: ..., level: INFO, channel: default, event: cache_lookup, hit: true, latency_ms: 1.5, entries: 4096}编译期约束以下三种用法都是编译期错误由logKVDispatch中的static_assert保证Support/include/Support/Log.h至少一对键值、总参数个数为偶数、最多四对、键必须可转换为std::string_viewMLOG_KV(LogLevel::INFO, a, 1, b); // error: needs pairs MLOG_KV(LogLevel::INFO, 7, value); // error: key must be a string MLOG_KV(LogLevel::INFO, a, 1, b, 2, c, 3, d, 4, e, 5); // error: at most four pairsLogRecord内部限定maxArgs 8、maxKVPairs 4一对占用两个参数槽位。当单个调用点需要超过四个字段时再发一条记录即可——该库不提供续行continuation形式。五、作用域计时SpanGuardSpanGuardSupport/include/Support/SpanGuard.h测量一个作用域的耗时并输出两条共享span_id的MLOG_KV记录#include Support/SpanGuard.h { M::Log::SpanGuard span(prefill); runPrefill(); }eventspan_start operationprefill span_id802754119... eventspan_end operationprefill span_id802754119... duration_us1423设计要点均有源码佐证结束记录由析构函数发出Support/include/Support/SpanGuard.h因此作用域内任何早退early return、异常路径都会正确关闭 span耗时取自steady_clock单调时钟span 中途的系统时间调整不会产生负值或失真Support/include/Support/SpanGuard.hoperation字符串是存储而非复制的其生命周期必须长于 guard——请传入字面量span_id由每个线程从随机 64 位基数自增生成thread_local计数器基数为两次std::random_device拼出的 64 位值见 Support/include/Support/SpanGuard.h因此跨线程天然互异且无需进程级共享计数器、不触碰共享缓存行作用域内其他记录不会自动继承span_id如需加入该 span请显式传span.getSpanId()。六、Mojo 接口Mojo 侧有包装 C Log 库的接口底层使用同一套fmt格式化因此同一条消息无论来自 Mojo 还是 C输出一致时间戳等动态部分除外mlogformat string here: {}, LogLevel.INFO mlog_infoall {} log convenience functions work参数会被捕获并转换为适合 FFI 调用的形态对应 C 侧的LogArg类。FFI 桥接层位于 Support/lib/LogFFI.cpp导出MLog_now、MLog_get_level、MLog_set_level、MLog_flush、MLog_write五个 C 符号其中MLog_write接收等级、通道、时间戳、格式串与序列化后的参数数组。该文件还通过static_assert锁定了两个跨语言约定LogArg必须可平凡复制且Mojo 通道被硬编码为 1对应Channel::Mojo。七、环境变量配置以下环境变量控制日志行为对应 Support/docs/Logging.md 中的完整配置表变量说明MODULAR_LOG_STDOUTfalse抑制 stdout 输出。默认 true。参见 sinks 说明MODULAR_LOG_FILE日志文件路径。未设置则不写文件MODULAR_LOG_ISO_TIME以YYYY-MM-DD:hh:mm:ss格式输出时间戳MODULAR_LOG_LEVEL最小可写级别对应上文宏名称MODULAR_LOG_MICROSECONDS时间戳中附带微秒MODULAR_LOG_NO_ENHANCED关闭全部前缀格式化含级别与时间戳MODULAR_LOG_NO_TIMESTAMP关闭时间戳但保留级别前缀MODULAR_LOG_JSON输出 JSON 日志行覆盖其他输出配置MODULAR_LOG_NO_SUMMARY抑制进程退出时的关闭摘要级别取值的具体规则从 Support/lib/Log.cpp 的parseLogLevelFromString可知MODULAR_LOG_LEVEL既接受数字0DEBUG、1INFO、2WARN、3ERROR、4FATAL也接受大小写不敏感的名称DEBUG/INFO/WARN/ERROR/FATAL解析失败时静默回退到WARN。配置文件的等价键源码还支持从配置文件读取同等配置Support/lib/Log.cpp键与上述环境变量一一对应log.stdout、log.file、log.iso_time、log.level、log.microseconds、log.no_enhanced、log.no_timestamp、log.json、log.enabled_channels、log.no_summary。其中log.enabled_channels是环境变量表中未列出的额外开关以;分隔的通道名列表支持all或具体通道名。若无法读取配置文件则回退为默认的仅 stdout 输出Support/lib/Log.cpp。日志通道Channel通道定义于 Support/include/Support/LogChannels.h目前有Default配置名default、Mojomojo、MLRTmlrt三个通道通道状态用std::bitset管理默认仅启用Default。每条记录都携带所属通道并在输出前缀与 JSON 的channel字段中体现。八、输出 Sink 机制Sink是抽象写目标Support/lib/Log.cpp当前实现两个StdoutSink写llvm::outs()。注意它只用自身互斥锁串行化经由此 sink 的访问而llvm::outs()是进程级全局流第三方直接写llvm::outs()的代码不在同步范围内FileSink追加写模式打开文件write/flush均加锁允许消费线程与外部调用flush()的线程并发安全访问raw_fd_ostream自身无内部同步。两条通道正交MODULAR_LOG_STDOUTtrue与MODULAR_LOG_FILE同时设置则双写false 空/未设置路径则日志整体关闭。九、异步日志、背压与丢弃无锁环形缓冲 专用消费线程每次日志调用都是非阻塞的生产者把记录序列化进一个无锁 MPSC多生产者单消费者环形缓冲后立即返回专用消费线程从缓冲读取并写入各 sink。消费者采用100 微秒轮询唤醒drainCv.wait_for(lock, 100us)环形缓冲容量为1 12 4096个槽位Support/include/Support/Log.h。因此日志输出可能比调用点稍晚出现且 sink 写入是批量的——环形缓冲排空时才 flush 到 OS而不是每条记录都 flush。丢弃是有意设计环形缓冲容量固定。当生产者入队速度超过消费者排空速度时新记录被丢弃而非阻塞调用方——日志绝不允许拖慢或卡住被观察的工作。enqueue()在ring.claim()失败时递增droppedRecords计数并返回Support/lib/Log.cpp。关闭摘要进程退出时Logger析构若生命周期内曾写入或丢弃过记录会向 stdout 打印摘要Support/lib/Log.cpp[Logger] shutdown: 142000 records written, 0 dropped非零丢弃数意味着日志速率超过了消费吞吐——应提高过滤级别或减少热路径上的日志量。用MODULAR_LOG_NO_SUMMARY可抑制该行。摘要通过std::printf输出是因为静态析构阶段llvm::outs()与文件 sink 可能已被销毁。强同步原语Logger::flush()提供阻塞直至此前所有入队记录写入全部 sink的语义记录目标消费计数、唤醒消费者、自旋等待最后再 flush 各 sinkSupport/lib/Log.cpp。消费线程仅在停止标志 零在途入队 队列排空三者同时满足时退出避免错过尚未发布序号的在途槽位Support/include/Support/Log.h。十、字符串参数的生命周期与 arena字符串参数在入队时被复制进每个槽位自带的 arena每槽256 字节字符串数据区从而在调用返回后依然有效若单条记录的全部字符串内容超过 256 字节超出部分被静默裁剪——请保持字符串参数短小。判断字符串是否复制的是长度而非存储期≤16 字节的值内联存储在LogArg自身SmallString标签永不进入 arena超过 16 字节的才复制——字符串字面量也不例外。arena 耗尽时剩余字符串被渲染为空串而不是悬垂指针Support/lib/Log.cpp这保证了消费线程永远读到有效内存。十一、JSON 输出格式NDJSON设置MODULAR_LOG_JSON后每行日志都是自包含的 JSON 对象 换行换行分隔 JSON / NDJSON。此时其他格式开关MODULAR_LOG_ISO_TIME、MODULAR_LOG_NO_TIMESTAMP等一律被忽略JSON 模式恒使用带微秒精度的完整 ISO 8601 UTC 时间戳如2026-03-16T12:00:00.123456ZSupport/lib/Log.cpp。每行只有两种形态MLOG记录携带message字段无其他自定义字段MLOG_KV记录携带键值对作为额外顶层字段没有message。官方 JSON Schema完整引自 Support/docs/Logging.md如下其中level枚举为DBG / INFO / WARN / ERR / FATL与源码getLogLevelPrefix去空格后一致必填字段为timestamp、level、channel{ $schema: https://json-schema.org/draft/2020-12/schema, type: object, required: [timestamp, level, channel], properties: { timestamp: { type: string, description: UTC time in ISO 8601 format with microsecond precision., examples: [2026-03-16T12:00:00.123456Z] }, level: { type: string, enum: [DBG, INFO, WARN, ERR, FATL], description: Severity level of the log message. }, channel: { type: string, description: Name of the channel the record was logged on. }, message: { type: string, description: Log message text. Present only on MLOG records. } }, oneOf: [ { required: [message], additionalProperties: false }, { not: {required: [message]}, minProperties: 4, additionalProperties: { type: [string, number, boolean], description: One MLOG_KV pair. Up to four are present. } } ] }注意MLOG_KV形态的minProperties: 4意味着除信封三字段外至少还有一个键值对——这与至少一对键值的编译期约束一致。数值与布尔值在 JSON 中保持原生类型见上文值类型保持到 JSON便于下游以数值维度过滤与聚合。十二、验证与进一步阅读仓库为日志库配备了完整的测试与基准可继续深入单元测试Support/unittests/Log/ 目录覆盖普通文本输出LogTest.cpp、键值渲染LogKeyValueTest.cpp、JSON 输出LogJSONOutputTest.cpp、通道控制LogChannelTest.cpp、配置文件解析LogConfigFileTest.cpp、边界情形LogEdgeCasesTest.cpp与 SpanGuardSpanGuardTest.cpp。测试通过设置环境变量后强制构造默认 logger 来验证 sink 行为是理解各配置项实际效果的最佳样例基准测试Support/benchmarks/Log/ 下的LogBenchmark.cpp、LogThroughputBenchmark.cpp、LogWorkloadBenchmark.cpp对应用尽可能少的周期完成记录这一首要目标可用于量化不同负载下该库的吞吐与丢弃表现核心头文件Support/include/Support/Log.h、Support/include/Support/SpanGuard.h、Support/include/Support/LogChannels.h实现文件Support/lib/Log.cpp、Support/lib/LogFFI.cppFFI 头文件Support/include/Support/LogFFI.h。十三、实战要点速查默认级别是 WARNDEBUG/INFO 消息默认不输出调试前先设MODULAR_LOG_LEVELDEBUG热路径用MLOG_KV并保持短键≤16 字符级别过滤时参数不求值键不会因 arena 裁剪而改名键避开timestamp/level/channel否则 JSON 模式下产生重复键单条记录字符串内容别超 256 字节超出部分静默截断SpanGuard的 operation 参数传字面量它只存指针不复制需要关联作用域内记录时显式传span.getSpanId()丢弃是特性而非 bugshutdown摘要中 dropped 非零时优先提高MODULAR_LOG_LEVEL而不是抱怨日志库MLOG_FATAL会 abort只用于不可恢复的严重错误需要结构化下游消费时开启MODULAR_LOG_JSON它输出 NDJSON覆盖其他一切格式开关。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Mojo 项目 Support 日志库实战指南：从 C++/Mojo 接口到异步日志与 JSON 结构化输出
Mojo 项目 Support 日志库实战指南从 C/Mojo 接口到异步日志与 JSON 结构化输出【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读Support/docs/Logging.md及其背后源码Support/include/Support/Log.h、Support/lib/Log.cpp共同构成了 Mojo 仓库中面向全栈各层编译器、运行时、工具链的统一日志基础设施。本文基于该文档与仓库源码系统讲解其 C/Mojo 双语言接口、五级日志宏、结构化键值记录、作用域计时、环境变量配置、异步无锁落盘机制以及 NDJSON 输出格式帮助你直接上手在 Mojo 或 C 组件中接入这套日志库并理解其日志绝不停顿被观察的工作这一核心设计取舍。一、日志库定位与设计目标该库用于从技术栈的任何一层compiler、runtime、tooling 等向文件或 stdout输出日志消息每条消息都携带时间戳与严重级别。其接口统一采用一个格式化字符串 一组参数的调用形态格式化语法基于fmt与std::format类似。从 Support/include/Support/Log.h 的源码注释可以看到三个按优先级排序的设计目标用尽可能少的周期完成日志记录性能第一记录后尽快输出消息可靠地输出所有消息。这三个目标有明确的取舍顺序最典型的表现就是当生产者速率超过消费者吞吐时新记录会被直接丢弃而不是阻塞调用方见下文异步日志与丢弃一节。这意味着该库本质上是面向生产环境、零阻塞语义的日志通道而非调试期全量保真工具。二、快速上手stdout 与文件双通道日志默认输出到 stdoutMODULAR_LOG_STDOUT未设置或为true时。若同时设置了MODULAR_LOG_FILE指向一个合法路径则输出同时写入文件两条通道相互正交可以只开其一、全开或全关。# 仅输出到 stdout默认 ./your_binary # 输出到文件 MODULAR_LOG_FILE/tmp/mojo.log ./your_binary # 同时输出到 stdout 和文件 MODULAR_LOG_STDOUTtrue MODULAR_LOG_FILE/tmp/mojo.log ./your_binary # 关闭日志stdoutfalse 且不设文件路径 MODULAR_LOG_STDOUTfalse ./your_binary从源码看文件 sink 以追加写方式打开CD_OpenAlways | FA_Write | OF_Append见 Support/lib/Log.cpp因此进程重启不会清空既有日志若文件无法打开会向errs()打印诊断并在 stdout 仍启用时降级为仅 stdout 输出否则不输出任何日志。三、C 接口MLOG 宏家族与五级日志所有 C 接口都收敛到MLOG(...)这一个宏展开为M::Log::log(...)并按其参数形态自动识别用法#include Support/Log.h // 单参数以 INFO 级别输出字符串 MLOG(hello); // - hello MLOG(); // - 仅输出换行 // 两个及以上参数格式化字符串 位置参数fmt 语法 MLOG({} {}, hello, world); // - hello world MLOG({} {} {}, hello, 42, 3.14); // 若第一个参数是 LogLevel则整体左移按指定级别输出 MLOG(LogLevel::DEBUG, {} {}, hello, 42);五个便捷宏分别对应五个级别等价于显式传入级别的MLOG宏级别语义MLOG_DEBUG(...)DEBUG开发与排障用的详细调试信息MLOG_INFO(...)INFO程序正常运行的一般性信息MLOG_WARN(...)WARN潜在问题告警不影响继续执行MLOG_ERROR(...)ERROR影响功能但允许程序继续的错误MLOG_FATAL(...)FATAL严重错误记录后终止程序MLOG_FATAL的行为由宏定义直接保证见 Support/include/Support/Log.h先记录日志再flush()强制排空最后调用std::abort()。级别数值与文本前缀LogLevel枚举定义于 Support/include/Support/Log.hDEBUG0, INFO1, WARN2, ERROR3, FATAL4数值越小越详细。级别过滤是最小可写级别语义——默认级别为WARNstd::atomicLogLevel level LogLevel::WARN;即低于 WARN 的 DEBUG/INFO 默认不输出。文本前缀见 Support/lib/Log.cppDBG / INFO / WARN / ERR / FATL带颜色的终端下还分别映射为亮黑、亮青、亮黄、亮红、红色。终端着色遵循NO_COLOR环境变量约定任何值、甚至空值都会禁用颜色TERMdumb或非交互式 stdout 时也会自动关闭颜色Support/lib/Log.cpp。参数支持的类型LogArgSupport/include/Support/Log.h是一块 POD 联合体支持bool / int64 / uint64 / float / double / 字符串 / 指针。任意整型参数会自动归约到 int64/uint64任意可转换为std::string_view的类型按字符串处理不支持的参数类型会在编译期通过static_assert直接报错Unsupported log argument type.。四、结构化键值记录MLOG_KVMLOG_KV(level, key, value, ...)输出的不是格式化消息而是命名字段。它接收交替出现的键值对最多四对且键必须是字符串MLOG_KV(LogLevel::INFO, event, span_start, operation, prefill, batch_id, batchId, request_id, requestId);两种渲染形态在 JSON 模式下每一对都成为顶层字段可直接作为下游如 Datadog的索引 facet 使用非 JSON 模式下则渲染为普通前缀之后的一串keyvaluetoken[INFO] eventspan_start operationprefill batch_id42 request_ida1b2c3同一记录在MODULAR_LOG_JSON下{timestamp: 2026-03-16T12:00:00.123456Z, level: INFO, channel: default, event: span_start, operation: prefill, batch_id: 42, request_id: a1b2c3}与 MLOG 的两个关键差异级别被过滤时参数完全不求值。MLOG_KV宏先比较getLogLevel() level通过后才进入logKVSupport/include/Support/Log.h因此它安全地放在热路径上昂贵的参数在记录被过滤时零成本// summarize() 只有在 DEBUG 级别启用时才会执行 MLOG_KV(LogLevel::DEBUG, event, batch_done, stats, summarize(batch));键原样写入。请避免使用timestamp、level、channel作为键——这些是 JSON 信封envelope字段键与信封字段重名会产生重复的 JSON 键源码在 Support/lib/Log.cpp 的注释中明确警告了这一点。键长度限制与 arena 裁剪键建议控制在16 字符以内。原因在 Support/include/Support/Log.hLogArg内部为短字符串预留了 16 字节的内联缓冲区SSO≤16 字节的字符串直接内联存储、从不进入 arena超过 16 字节的字符串则被复制进记录共享的256 字节 arena而 arena 是裁剪而非扩容的——过长的键会被静默截断这等于悄悄改名的字段且两个共享前缀的长键可能被裁剪成同一个名字。值类型保持到 JSON值在 JSON 中保留原生类型数字与布尔不带引号从而可作为数值而非字符串参与下游过滤MLOG_KV(LogLevel::INFO, event, cache_lookup, hit, found, // bool - true latency_ms, elapsedMs, // double - 1.5 entries, cache.size()); // integer - 4096{timestamp: ..., level: INFO, channel: default, event: cache_lookup, hit: true, latency_ms: 1.5, entries: 4096}编译期约束以下三种用法都是编译期错误由logKVDispatch中的static_assert保证Support/include/Support/Log.h至少一对键值、总参数个数为偶数、最多四对、键必须可转换为std::string_viewMLOG_KV(LogLevel::INFO, a, 1, b); // error: needs pairs MLOG_KV(LogLevel::INFO, 7, value); // error: key must be a string MLOG_KV(LogLevel::INFO, a, 1, b, 2, c, 3, d, 4, e, 5); // error: at most four pairsLogRecord内部限定maxArgs 8、maxKVPairs 4一对占用两个参数槽位。当单个调用点需要超过四个字段时再发一条记录即可——该库不提供续行continuation形式。五、作用域计时SpanGuardSpanGuardSupport/include/Support/SpanGuard.h测量一个作用域的耗时并输出两条共享span_id的MLOG_KV记录#include Support/SpanGuard.h { M::Log::SpanGuard span(prefill); runPrefill(); }eventspan_start operationprefill span_id802754119... eventspan_end operationprefill span_id802754119... duration_us1423设计要点均有源码佐证结束记录由析构函数发出Support/include/Support/SpanGuard.h因此作用域内任何早退early return、异常路径都会正确关闭 span耗时取自steady_clock单调时钟span 中途的系统时间调整不会产生负值或失真Support/include/Support/SpanGuard.hoperation字符串是存储而非复制的其生命周期必须长于 guard——请传入字面量span_id由每个线程从随机 64 位基数自增生成thread_local计数器基数为两次std::random_device拼出的 64 位值见 Support/include/Support/SpanGuard.h因此跨线程天然互异且无需进程级共享计数器、不触碰共享缓存行作用域内其他记录不会自动继承span_id如需加入该 span请显式传span.getSpanId()。六、Mojo 接口Mojo 侧有包装 C Log 库的接口底层使用同一套fmt格式化因此同一条消息无论来自 Mojo 还是 C输出一致时间戳等动态部分除外mlogformat string here: {}, LogLevel.INFO mlog_infoall {} log convenience functions work参数会被捕获并转换为适合 FFI 调用的形态对应 C 侧的LogArg类。FFI 桥接层位于 Support/lib/LogFFI.cpp导出MLog_now、MLog_get_level、MLog_set_level、MLog_flush、MLog_write五个 C 符号其中MLog_write接收等级、通道、时间戳、格式串与序列化后的参数数组。该文件还通过static_assert锁定了两个跨语言约定LogArg必须可平凡复制且Mojo 通道被硬编码为 1对应Channel::Mojo。七、环境变量配置以下环境变量控制日志行为对应 Support/docs/Logging.md 中的完整配置表变量说明MODULAR_LOG_STDOUTfalse抑制 stdout 输出。默认 true。参见 sinks 说明MODULAR_LOG_FILE日志文件路径。未设置则不写文件MODULAR_LOG_ISO_TIME以YYYY-MM-DD:hh:mm:ss格式输出时间戳MODULAR_LOG_LEVEL最小可写级别对应上文宏名称MODULAR_LOG_MICROSECONDS时间戳中附带微秒MODULAR_LOG_NO_ENHANCED关闭全部前缀格式化含级别与时间戳MODULAR_LOG_NO_TIMESTAMP关闭时间戳但保留级别前缀MODULAR_LOG_JSON输出 JSON 日志行覆盖其他输出配置MODULAR_LOG_NO_SUMMARY抑制进程退出时的关闭摘要级别取值的具体规则从 Support/lib/Log.cpp 的parseLogLevelFromString可知MODULAR_LOG_LEVEL既接受数字0DEBUG、1INFO、2WARN、3ERROR、4FATAL也接受大小写不敏感的名称DEBUG/INFO/WARN/ERROR/FATAL解析失败时静默回退到WARN。配置文件的等价键源码还支持从配置文件读取同等配置Support/lib/Log.cpp键与上述环境变量一一对应log.stdout、log.file、log.iso_time、log.level、log.microseconds、log.no_enhanced、log.no_timestamp、log.json、log.enabled_channels、log.no_summary。其中log.enabled_channels是环境变量表中未列出的额外开关以;分隔的通道名列表支持all或具体通道名。若无法读取配置文件则回退为默认的仅 stdout 输出Support/lib/Log.cpp。日志通道Channel通道定义于 Support/include/Support/LogChannels.h目前有Default配置名default、Mojomojo、MLRTmlrt三个通道通道状态用std::bitset管理默认仅启用Default。每条记录都携带所属通道并在输出前缀与 JSON 的channel字段中体现。八、输出 Sink 机制Sink是抽象写目标Support/lib/Log.cpp当前实现两个StdoutSink写llvm::outs()。注意它只用自身互斥锁串行化经由此 sink 的访问而llvm::outs()是进程级全局流第三方直接写llvm::outs()的代码不在同步范围内FileSink追加写模式打开文件write/flush均加锁允许消费线程与外部调用flush()的线程并发安全访问raw_fd_ostream自身无内部同步。两条通道正交MODULAR_LOG_STDOUTtrue与MODULAR_LOG_FILE同时设置则双写false 空/未设置路径则日志整体关闭。九、异步日志、背压与丢弃无锁环形缓冲 专用消费线程每次日志调用都是非阻塞的生产者把记录序列化进一个无锁 MPSC多生产者单消费者环形缓冲后立即返回专用消费线程从缓冲读取并写入各 sink。消费者采用100 微秒轮询唤醒drainCv.wait_for(lock, 100us)环形缓冲容量为1 12 4096个槽位Support/include/Support/Log.h。因此日志输出可能比调用点稍晚出现且 sink 写入是批量的——环形缓冲排空时才 flush 到 OS而不是每条记录都 flush。丢弃是有意设计环形缓冲容量固定。当生产者入队速度超过消费者排空速度时新记录被丢弃而非阻塞调用方——日志绝不允许拖慢或卡住被观察的工作。enqueue()在ring.claim()失败时递增droppedRecords计数并返回Support/lib/Log.cpp。关闭摘要进程退出时Logger析构若生命周期内曾写入或丢弃过记录会向 stdout 打印摘要Support/lib/Log.cpp[Logger] shutdown: 142000 records written, 0 dropped非零丢弃数意味着日志速率超过了消费吞吐——应提高过滤级别或减少热路径上的日志量。用MODULAR_LOG_NO_SUMMARY可抑制该行。摘要通过std::printf输出是因为静态析构阶段llvm::outs()与文件 sink 可能已被销毁。强同步原语Logger::flush()提供阻塞直至此前所有入队记录写入全部 sink的语义记录目标消费计数、唤醒消费者、自旋等待最后再 flush 各 sinkSupport/lib/Log.cpp。消费线程仅在停止标志 零在途入队 队列排空三者同时满足时退出避免错过尚未发布序号的在途槽位Support/include/Support/Log.h。十、字符串参数的生命周期与 arena字符串参数在入队时被复制进每个槽位自带的 arena每槽256 字节字符串数据区从而在调用返回后依然有效若单条记录的全部字符串内容超过 256 字节超出部分被静默裁剪——请保持字符串参数短小。判断字符串是否复制的是长度而非存储期≤16 字节的值内联存储在LogArg自身SmallString标签永不进入 arena超过 16 字节的才复制——字符串字面量也不例外。arena 耗尽时剩余字符串被渲染为空串而不是悬垂指针Support/lib/Log.cpp这保证了消费线程永远读到有效内存。十一、JSON 输出格式NDJSON设置MODULAR_LOG_JSON后每行日志都是自包含的 JSON 对象 换行换行分隔 JSON / NDJSON。此时其他格式开关MODULAR_LOG_ISO_TIME、MODULAR_LOG_NO_TIMESTAMP等一律被忽略JSON 模式恒使用带微秒精度的完整 ISO 8601 UTC 时间戳如2026-03-16T12:00:00.123456ZSupport/lib/Log.cpp。每行只有两种形态MLOG记录携带message字段无其他自定义字段MLOG_KV记录携带键值对作为额外顶层字段没有message。官方 JSON Schema完整引自 Support/docs/Logging.md如下其中level枚举为DBG / INFO / WARN / ERR / FATL与源码getLogLevelPrefix去空格后一致必填字段为timestamp、level、channel{ $schema: https://json-schema.org/draft/2020-12/schema, type: object, required: [timestamp, level, channel], properties: { timestamp: { type: string, description: UTC time in ISO 8601 format with microsecond precision., examples: [2026-03-16T12:00:00.123456Z] }, level: { type: string, enum: [DBG, INFO, WARN, ERR, FATL], description: Severity level of the log message. }, channel: { type: string, description: Name of the channel the record was logged on. }, message: { type: string, description: Log message text. Present only on MLOG records. } }, oneOf: [ { required: [message], additionalProperties: false }, { not: {required: [message]}, minProperties: 4, additionalProperties: { type: [string, number, boolean], description: One MLOG_KV pair. Up to four are present. } } ] }注意MLOG_KV形态的minProperties: 4意味着除信封三字段外至少还有一个键值对——这与至少一对键值的编译期约束一致。数值与布尔值在 JSON 中保持原生类型见上文值类型保持到 JSON便于下游以数值维度过滤与聚合。十二、验证与进一步阅读仓库为日志库配备了完整的测试与基准可继续深入单元测试Support/unittests/Log/ 目录覆盖普通文本输出LogTest.cpp、键值渲染LogKeyValueTest.cpp、JSON 输出LogJSONOutputTest.cpp、通道控制LogChannelTest.cpp、配置文件解析LogConfigFileTest.cpp、边界情形LogEdgeCasesTest.cpp与 SpanGuardSpanGuardTest.cpp。测试通过设置环境变量后强制构造默认 logger 来验证 sink 行为是理解各配置项实际效果的最佳样例基准测试Support/benchmarks/Log/ 下的LogBenchmark.cpp、LogThroughputBenchmark.cpp、LogWorkloadBenchmark.cpp对应用尽可能少的周期完成记录这一首要目标可用于量化不同负载下该库的吞吐与丢弃表现核心头文件Support/include/Support/Log.h、Support/include/Support/SpanGuard.h、Support/include/Support/LogChannels.h实现文件Support/lib/Log.cpp、Support/lib/LogFFI.cppFFI 头文件Support/include/Support/LogFFI.h。十三、实战要点速查默认级别是 WARNDEBUG/INFO 消息默认不输出调试前先设MODULAR_LOG_LEVELDEBUG热路径用MLOG_KV并保持短键≤16 字符级别过滤时参数不求值键不会因 arena 裁剪而改名键避开timestamp/level/channel否则 JSON 模式下产生重复键单条记录字符串内容别超 256 字节超出部分静默截断SpanGuard的 operation 参数传字面量它只存指针不复制需要关联作用域内记录时显式传span.getSpanId()丢弃是特性而非 bugshutdown摘要中 dropped 非零时优先提高MODULAR_LOG_LEVEL而不是抱怨日志库MLOG_FATAL会 abort只用于不可恢复的严重错误需要结构化下游消费时开启MODULAR_LOG_JSON它输出 NDJSON覆盖其他一切格式开关。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考