NeuronLogger — the C++ Logging Singleton & Boost.Log Sinks

All addresses on this page apply to neuronx_cc 2.24.5133.0+58f8de22 (cp310). NeuronLogger addresses (0x759….) are virtual addresses in the statically-linked, unstripped neuronxcc/starfish/bin/hlo-opt, where VA == file offset for .text/.rodata. The logging:: Boost.Log symbols are cited from neuronxcc/starfish/bin/walrus_bugpoint_driver (which statically links liblogging), so those VAs are walrus-local; the standalone liblogging.so re-bases them. Other versions and other tools will differ.

Abstract

Native compiler diagnostics in neuronx-cc are produced by two completely separate C++ loggers that share nothing but an enum and a default filename. The first, NeuronLogger, is a Meyers singleton compiled directly into each big native tool (hlo-opt, hlo2penguin, walrus, …). It is a hand-rolled mini-logger: three std::ostringstream buffers, three integer severity thresholds, a default logfile name "log-neuron-cc.txt", and a flush() that opens that file and dumps one buffer. It never touches Boost.Log. The second, logging::Logger, lives in liblogging and is a full boost::log::v2s_mt_posix severity/channel logger with a six-element attribute set, a phoenix formatter, and two asynchronous sinks (a colorized console MergedSink and a file text_ostream_backend). The Python neuronxlogger façade (3.19) drives the second one; library-internal NeuronLogger::getInstance() << … call sites drive the first.

The reason this matters to a reimplementer is that the two loggers use two different LogLevel encodings. NeuronLogger gates with a compact integer ordinal (defaults: console threshold 4, file threshold 2) where a lower threshold is chattier. logging::LogLevel is the public enum {TRACE=0, DEBUG=10, INFO=20, WARNING=30, ERROR=40, FATAL=50, USER=60, OFF=70} — a 0,10,…,70 scale, proven byte-for-byte from the jump table in logging::operator<<(ostream&, LogLevel). A bridge table, neuronToABSLLogLevelMapping, maps the compact ordinals to absl::LogSeverity. Conflating the two scales is the single most likely reimplementation error.

This page reconstructs both: the NeuronLogger struct layout (≈0x4A8 bytes, dominated by three 0x178-byte ostringstreams), its lazy-singleton getInstance, its per-record operator<< format, its getCurrentTime microsecond clock, and its flush; then the logging::Logger Boost.Log type, attribute set, formatter term order, and the two sink front-ends.

For reimplementation, the contract is:

• The NeuronLogger struct layout and the three threshold fields (which offset gates console vs file).
• The Meyers-singleton getInstance lazy init (guard byte, instance static, __cxa_atexit teardown).
• The per-record emission format and the developer log line it produces.
• The logging::LogLevel 0..70 enum and how it differs from the compact NeuronLogger ordinal.
• The logging::Logger Boost.Log source type, the six attributes, the phoenix formatter term order, and the two async sinks.

GOTCHA — the Boost.Log v2s_mt_posix severity/channel logger, with its level_attr / pid_attr / module_attr / source_attr / smessage attributes, is logging::Logger in liblogging — not NeuronLogger. The hlo-opt NeuronLogger singleton is a 3×ostringstream mini-logger that touches only std::filebuf/std::ostream/std::stringbuf; its flush() @0x759d060 references no boost::log symbol at all. This page keeps the two apart by name everywhere.

1. The Two-Logger Boundary

The strongest evidence that there are two distinct loggers is symbolic and direct: the unstripped hlo-opt exports the entire NeuronLogger::* method family with its own singleton storage, while walrus_bugpoint_driver (and the standalone liblogging.so) export a separate logging::Logger::* family with its own static sink front-ends. There is no symbol, vtable, or data pointer linking one to the other.

The only contract they share is the LogLevel name set and the default filename "log-neuron-cc.txt". The encodings are different (§5), the storage is different, the format is different, and neither calls the other.

GOTCHA — "they share the enum names" does not mean they share the enum values. NeuronLogger's threshold compares use a compact ordinal (0,1,2,3,4,…); logging::LogLevel uses 0,10,20,…,70. The neuronToABSLLogLevelMapping bridge (§5b) keys on the compact ordinal — so it is NeuronLogger's scale, not logging::Logger's. A reimplementer who feeds logging::LogLevel::ERROR (40) into a NeuronLogger threshold gets a value far above the 4 default and silences nothing it intended to.

2. NeuronLogger — Singleton & Lifecycle

Purpose

NeuronLogger is the in-process developer logger for the native tools. A call site does NeuronLogger::getInstance().setSourceFile(__FILE__).setSourceLine(__LINE__).setCurLogLevel(lvl) << "msg"; the streamed record is gated by the per-instance thresholds, timestamped, prefixed with a level tag and file:line, and accumulated into one of three ostringstreams. flush() (also called by the destructor at exit) rewrites log-neuron-cc.txt with the file buffer.

Entry Point

NeuronLogger::getInstance()                  0x759c740 (123 B)   ── Meyers singleton
  ├─ guard byte _ZGVZ…E8instance @0x9aa2828  ── first-use latch
  ├─ __cxa_guard_acquire / __cxa_guard_release
  ├─ NeuronLogger::NeuronLogger() (C2)       0x759c2f0 (1077 B)  ── builds state
  └─ __cxa_atexit(NeuronLogger::~NeuronLogger (D1) @0x759d490, &instance, __dso_handle)
       └─ ~NeuronLogger() calls flush()      0x759d060 (1065 B)  ── final dump

Algorithm

The disassembly at 0x759c740 is a textbook GCC Meyers singleton: a fast path that returns &instance when the guard byte is already set, and a slow path under __cxa_guard_acquire that constructs once and registers __cxa_atexit.

NeuronLogger* NeuronLogger::getInstance():            // 0x759c740
    if (guard_byte /* @0x9aa2828 */ != 0)             // movzx eax,[guard]; test al,al
        return &instance;                             // @0x9aa2840 — fast path

    if (__cxa_guard_acquire(&guard_byte) != 0):        // 0x759c767 — we win the race
        NeuronLogger::NeuronLogger(&instance);         // C2 @0x759c2f0
        __cxa_atexit(&NeuronLogger::~NeuronLogger,     // D1 @0x759d490
                     &instance, &__dso_handle);        // 0x759c799
        __cxa_guard_release(&guard_byte);              // 0x759c7a3
    return &instance;                                  // 0x759c7ac
    // cold path (0x759c726): __cxa_guard_abort + _Unwind_Resume on ctor throw

NOTE — the guard byte and the instance object are adjacent in .bss: guard at 0x9aa2828, object at 0x9aa2840, a 24-byte gap that is alignment padding for the singleton's ostringstreams. The __cxa_atexit argument order (destructor, &instance, &__dso_handle) is the standard libstdc++ contract — the same one used by the unrelated _GLOBAL__sub_I static initializer that builds the bridge table (§5b).

Function Map

operator<< is instantiated per argument type — lsIcE (0x1e80d60), lsImE (unsigned long, 0x1f20380), lsINSt…basic_string… (0x1e74790), lsISt17basic_string_view… (0x1e7f3b0), and the fixed char-array overloads lsIA{2,3,5,6,10,11,14,17,26}_cE (one per string-literal length). All funnel through shouldLogToFile/getCurrentTime, so the format below is shared.

3. NeuronLogger — Struct Layout

Layout

Reconstructed from the constructor stores at 0x759c2f0, the accessor offsets, and flush/dtor. The object is dominated by three libstdc++ std::ostringstreams, each 0x178 bytes (matching the ios_base + basic_ios + embedded stringbuf + locale stride), at +0x48, +0x1C0, +0x338. The last stream's ios::init reaches +0x488, so the total size is ≈0x4A8.

Considerations

The single 64-bit store mov rax, 0x200000002 ; mov [rdi+0x18], rax writes two fields at once: fileThreshold(+0x18)=2 (low dword) and curLogLevel(+0x1C)=2 (high dword). consoleThreshold(+0x14)=4 is a separate mov dword[rdi+0x14],4. So the default posture is console quieter than file (console threshold 4 > file threshold 2): more records reach the file than the console.

QUIRK — which stream is the file buffer is not the first one. flush() dumps streamFile at +0x1C0, the second ostringstream, not streamA at +0x48. This is proven by flush reading the stringbuf data/end/base of the +0x1C0 object ([rbx+0x1F0] data ptr, [rbx+0x1E0] end, [rbx+0x210] base, [rbx+0x208] length). A reimplementer who assumes "first stream = file" dumps the wrong buffer.

NOTE — the +0x20 byte (init 0) and the role of the third stream streamC at +0x338 are [INFERRED]. The byte is plausibly an "enabled/initialized" flag and streamC a console/stderr mirror of streamA, but only streamFile (+0x1C0) is anchored by flush.

4. NeuronLogger — Record Format, Clock & Flush

Algorithm — per-record operator<<

Every operator<< overload, gated by shouldLogToFile(curLogLevel), emits a fixed prefix into the file buffer before the message. The char overload at 0x1e80d60 shows the sequence and the level-tag selection.

NeuronLogger& operator<<(...):                         // e.g. 0x1e80d60
    gate = shouldLogToFile(this->curLogLevel);         // 0x1e80d96
    tag2 = (this->curLogLevel <= 3) ? "I " : "E ";     // 0x1e80db3 cmp [+0x1C],3; setle
                                                       //  (2-char level tag, len=2)
    stream << getCurrentTime();                        // 0x1e80e03 "YYYY-MM-DD HH:MM:SS.uuuuuu"
    stream << ": ";                                    // asc_24B70D @0x24b70d
    stream << tag2;                                    // selected level tag
    stream << this->srcFile;                           // [+0x08], strlen'd
    stream << ":";                                     // delim @0x252fee
    stream << this->srcLine;                           // [+0x10] as int
    stream << "] ";                                    // asc_25F073 @0x25f073
    stream << <message…>;

The produced developer line is, for example:

2026-04-08 21:07:10.123456: E /path/to/file.cc:123] message text

NOTE — the two-character tag is selected by curLogLevel <= 3 (setle) at 0x1e80db3, and the tag length (2) is stored alongside. The exact bytes of the two tags ("I " for the chatty branch, "E " for the severe branch) come from the level-tag rodata at ds:0x2045 + idx*4. The gate logic is read off the setle; the tag-byte decode is [INFERRED] from that rodata indexing.

Algorithm — getCurrentTime

std::string getCurrentTime():                          // 0x759c8e0
    ns  = system_clock::now().time_since_epoch();       // nanoseconds
    sec = ns / 1'000'000'000;                            // magic 0x112E0BE826D694B3, sar 26
    usec= (ns / 1000) % 1'000'000;                       // 0..999999
    tm  = localtime(&sec);
    ss << put_time(tm, "%Y-%m-%d %H:%M:%S");             // fmt @hlo-opt rodata 0x2495BF
    ss << ".";
    ss << setw(6) << setfill('0') << usec;               // 6-digit zero-pad: mov [..],6; fill '0'
    return ss.str();

The verbatim format string "%Y-%m-%d %H:%M:%S" is confirmed present in hlo-opt rodata, followed by a literal "." and a 6-digit zero-padded microsecond field.

Algorithm — flush

void flush():                                          // 0x759d060
    ofstream ofs;                                       // local ios_base + filebuf
    ofs.open(this->logfileName /* [rbx+0x28] */,        // 0x759d12b mov rsi,[rbx+0x28]
             mode = 0x11);                              // 0x759d12f mov edx,0x11 = in|trunc
    if (ofs.is_open()):                                 // 0x759d169 __basic_file::is_open
        ofs << streamFile.str();                        // dumps +0x1C0 buffer (data @[+0x1F0])
        ofs.put('\n'); ofs.flush();
        filebuf.close();
    // re-sync the file stringbuf so the next batch starts clean

GOTCHA — the open mode is 0x11 = in | trunc (decoded against libstdc++ _Ios_Openmode{in=1, out=2, ate=4, app=8, trunc=0x10, binary=0x20}). Because every flush() truncates, the file is rewritten from the accumulated buffer each time — it is not an append log. A reimplementer who opens with app produces a growing file with duplicated history; the original produces a single snapshot of the current buffer.

5. LogLevel — Two Encodings

5a. logging::LogLevel (liblogging) — the 0..70 scale

Decoded byte-for-byte from the cmp/jz jump table in logging::operator<<(ostream&, LogLevel) (0x6ee358) and the rodata name strings. Each case compares the level against the constant shown and emits the named string.

The endpoints are proven: the operator<< switch compares the top of the chain against 0x46 (cmp [var_C], 0x46h at 0x6ee367, with jg falling through to the no-op exit for anything above 70) and bottoms out at cmp …, 0 → "TRACE". This is the same enum the Python neuronxlogger façade mirrors (TRACE = NOTSET+5, FATAL = CRITICAL, USER = CRITICAL+10, OFF = CRITICAL+20; cross-ref 3.19).

5b. neuronToABSLLogLevelMapping — the bridge to absl

A std::unordered_map<LogLevel, absl::LogSeverity> built once at static-init time by _GLOBAL__sub_I__ZN12NeuronLoggerC2Ev (0x759d670). The init stack-builds a 6-pair array (each 8-byte pair = {key (low dword), value (high dword)}) and hands its [begin, end) to the _Hashtable ctor. absl::LogSeverity = {INFO=0, WARNING=1, ERROR=2, FATAL=3}.

QUIRK — these keys are the compact 1..6 ordinal, not the 0,10,…,70 scale of §5a. That is the proof that two LogLevel encodings coexist in the same process: logging::LogLevel is the 10-step public enum, while NeuronLogger's thresholds and this bridge table speak the compact ordinal. The six pairs themselves are read directly from the mov immediates at 0x759d6ba–0x759d6e6; the exact key→severity pairing is [INFERRED], because the on-stack pair ordering versus map insertion order was not single-stepped.

5c. NeuronLogger compact threshold gates

bool shouldLogToConsole(int level): return consoleThreshold(+0x14) <= level;  // cmp/setle
bool shouldLogToFile(int level):    return fileThreshold(+0x18)    <= level;  // cmp/setle

A record reaches a sink when threshold <= record_level — i.e. a lower threshold is chattier. Defaults: console 4, file 2, current 2. The operator<< additionally branches on curLogLevel <= 3 to pick the 2-char tag (§4). This compact ordinal is the severity scale NeuronLogger actually gates on; it is unrelated to the 10-step logging::LogLevel.

5d. liblogging level accessors

isEnabledFor does not read a local int and compare; it opens a Boost.Log record tagged with the severity keyword and lets the core's filter predicate (§6) decide — the canonical Boost.Log pattern. to_log_level guards a one-time int→LogLevel table init (touches a guard near fileSinkFrontEnd).

6. logging::Logger — the Boost.Log Machinery

Logger source type

The logging::Logger source is a boost::log::v2s_mt_posix composite logger. The full demangled type (from basic_composite_logger…C2 at walrus 0x61e6a0 and the constructor symbol) is:

logging::Logger =
  basic_composite_logger< char, logging::Logger, single_thread_model,
    features<
      severity< logging::LogLevel >,         // severity feature
      channel< std::string >,                // channel feature; default channel "Logging"
      mpl::quote1< logging_internal::type_feature >   // custom LogType feature
    > >

So it is severity + channel + one custom feature (type_feature, carrying logging::LogType). The default channel string is "Logging" (rodata). The threading model is single_thread_model (the records are pumped into async sinks; the model refers to the source, not the sinks).

Anchors: demangled symbols.

Attribute set (6 members)

Each attribute tag is a logging_internal::tag::* with a get_name() export. The phoenix formatter and the value-ref machinery reference all six.

NOTE — the attribute set has six members, not the five (level/pid/module/source/smessage) that the formatter signature suggests at a glance: the demangled formatter plus the type_dispatcher<logging::LogType> / attribute_value_impl<logging::LogType> symbols add type_attr (logging::LogType).

Formatter — phoenix term order

The formatter is a boost::log::v2s_mt_posix::basic_formatter<char> built from a phoenix shift_left (<<) expression tree. Reading the deepest-nested-first term order out of the demangled basic_expr<…shift_left…> type gives:

stream << function_eval[ std::string(*)() ]            // timestamp function (no-arg string fn)
       << A2_c                                          // 2-char literal separator
       << attribute_actor<LogLevel, level_attr>(fallback_to_none)
       << A2_c                                          // 2-char literal separator
       << value_ref<id<process>, pid_attr>              // process id
       << value_ref<string, module_attr>                // module
       << A3_c                                          // 3-char literal separator
       << value_ref<string, source_attr>                // source
       << A4_c                                          // 4-char literal separator
       << tag::smessage                                 // the message body

The separator widths (A2 / A3 / A4 — array-of-char terminals A2_c, A3_c, A4_c) are read directly from the formatter type. The printable rodata neighbors of the level table give the building blocks — " (", "]: ", the "module" keyword. The formatter imbues en_US.UTF-8 (rodata string confirmed).

NOTE — the exact bytes of the A2/A3/A4 literals are not byte-extracted from the compiled phoenix tree, so the fully-rendered Boost line layout is [INFERRED]. The term order, the attribute types, and the separator widths are read off the demangled formatter type.

Two async sinks

Both sinks are asynchronous_sink<…, unbounded_fifo_queue> registered on core::get().

Static sink front-end handles in liblogging .bss: consoleSinkFrontEnd (0x26446c0 in walrus), fileSinkFrontEnd (0x26446e0).

The console write path is MergedSink::consume(record_view const&, std::string const& formatted), which routes between STDOUT and STDERR by severity and wraps severe lines in ANSI color — red "\x1b[31;20m" ([31;20m confirmed in rodata) with reset "\x1b[0m". The channel names "STDOUT" and "STDERR" are confirmed strings.

One-time-setup guards

Re-registering a sink is a fatal error. The exact strings are confirmed in the binary:

Duplicate attempts to setup console logging.
Duplicate attempts to setup file logging.

GOTCHA — the duplicate-setup checks make setup_console_logging / setup_logfile_logging one-shot. A reimplementation that re-initializes logging on, say, a second compile pass in the same process must guard against it or it aborts. (The companion "Can't dump trace to an empty filename" guard belongs to the standalone liblogging.so; its presence in the walrus copy is [INFERRED] — the string was not located there.)

Related Components

Cross-References

• Python logging façade — the neuronxlogger Python side that drives the Boost.Log logging::Logger, with the matching TRACE/USER/OFF mapping
• Diagnostic & Error-Code Catalog — 3.20, diagnostic codes emitted at the ERROR/FATAL severities
• The neuronx-cc Command Dispatcher & Subcommand Model — the per-process model under which each tool instantiates its own logger