Skip to content

feat: rename log macros to debug!/info!/warn!/error! + add trace level and spans#1

Merged
trunkszi merged 1 commit into
mainfrom
api/log-macro-naming
May 28, 2026
Merged

feat: rename log macros to debug!/info!/warn!/error! + add trace level and spans#1
trunkszi merged 1 commit into
mainfrom
api/log-macro-naming

Conversation

@trunkszi

Copy link
Copy Markdown
Owner

Summary

  • Rename level macros to align with the Rust logging ecosystem: logd!/logi!/logw!/loge!debug!/info!/warn!/error!
  • Add Trace severity (Level::TRC = 0) and a trace! macro; existing levels shift +1 (DBG=1, INF=2, WRN=3, ERR=4, OFF=5)
  • Add a lightweight span subsystem (Span, SpanGuard, SpanId, Instrument future wrapper) with the span! macro and a {span} header pattern token

Breaking changes

  • All logd!/logi!/logw!/loge! call sites must migrate to debug!/info!/warn!/error!. No deprecated aliases retained.
  • Level numeric repr shifts: persisted/serialized level bytes from prior builds are no longer compatible (ferrilog has no on-disk Level serialization today, so this is internal-only).
  • StaticHeaderWriteFn signature gains a trailing u64 (span_id). Any custom static header writer must add the parameter.

Implementation notes

  • Payload layout grows by 8 bytes: [info_ptr][timestamp][span_id][encoded args...]
  • Argument-order decision: span_id is placed at the end of write_record / write_header signatures. An earlier in-middle placement caused 60–140% regressions on the header_output benches because AAPCS64 spilled &str.len to the stack. Moving span_id last restores all benches to noise threshold and leaves thread_name/location in argument registers.

Test plan

  • cargo check --workspace --all-features --all-targets
  • cargo test --workspace --all-features — 71 tests pass, includes new span::tests::enter_and_drop_restore_current_span, span::tests::span_records_parent_id, header::tests::span_header_token_renders_dash_for_root_and_decimal_for_span
  • cargo clippy --workspace --all-features --all-targets -- -D warnings — zero warnings
  • cargo bench (latency_throughput, core_component_bench, ferrilog_bench) — 0 regressed, 1 improved, rest within noise; some hot-path cases ~6% faster than the pre-span baseline
  • Manual span smoke test: nested spans render span=-span=1span=2span=1span=- correctly
  • Examples 01/02/04/07 run with expected output

@trunkszi trunkszi force-pushed the api/log-macro-naming branch from 91afbef to 04b99de Compare May 28, 2026 12:59
Rename level macros to align with the Rust logging ecosystem (log/tracing):
  logd! -> debug!
  logi! -> info!
  logw! -> warn!
  loge! -> error!

Add a new Trace severity (Level::TRC = 0) and trace! macro for the lowest
level. The existing levels shift up by one (DBG=1, INF=2, WRN=3, ERR=4,
OFF=5).

Add a lightweight span subsystem:
  - core/src/span.rs: Span, SpanGuard, SpanId, StaticSpanInfo,
    Instrument/Instrumented (future wrapper), thread-local span stack
    (MAX_SPAN_DEPTH=64).
  - span! macro for ergonomic creation.
  - Header pattern gains a {span} token; renders "-" at the root and the
    decimal span id when a span is entered.

Payload layout grows by 8 bytes:
  [info_ptr][timestamp][span_id][encoded args...]

Note on argument order: span_id is placed at the *end* of write_record /
write_header signatures (not adjacent to level) so that thread_name and
location stay in AAPCS64 argument registers. An earlier in-middle
placement pushed &str length onto the stack and caused 60-140%
regressions on the header_output benches; moving span_id last restores
all benches to noise threshold (some hot-path cases now ~6% faster than
the pre-span baseline).

Verification:
  - cargo check / clippy / test (71 tests): all green, includes 3 new
    span and header tests.
  - cargo bench (latency_throughput, core_component_bench,
    ferrilog_bench): 0 regressed, 1 improved, rest within noise.
  - Manual span smoke test: nested outer/inner spans render correct
    {span} ids ("-" -> "1" -> "2" -> "1" -> "-").
@trunkszi trunkszi force-pushed the api/log-macro-naming branch from 04b99de to 73e06db Compare May 28, 2026 13:01
@trunkszi trunkszi merged commit c9d18b3 into main May 28, 2026
1 check passed
@trunkszi trunkszi deleted the api/log-macro-naming branch May 28, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant