BitLogger/docs/api/logger-trace.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
logger-trace	api	logging	20260512	Emit a trace-level record through the logger using the lowest built-in severity shortcut.	logger trace sync public

Logger-trace

Emit a trace-level record through the synchronous logger. This is the convenience wrapper for log(Level::Trace, ...).

Interface

pub fn[S : Sink] Logger::trace(self : Logger[S], message : String, fields~ : Array[Field] = []) -> Unit {}

input

• self : Logger[S] - Logger that should emit the trace record.
• message : String - Trace message text.
• fields : Array[Field] - Optional structured fields attached to the record.

output

• Unit - No return value. The record is handled according to the logger threshold and sink pipeline.

Explanation

Detailed rules explaining key parameters and behaviors

• This helper delegates to log(Level::Trace, ...).
• Trace is the lowest built-in severity and is often disabled in production.
• This helper does not accept a per-call target override. It uses the logger's stored target unless the logger was derived earlier with with_target(...) or child(...).
• Context, filtering, patching, and queue wrappers still apply through the logger sink chain.

How to Use

Here are some specific examples provided.

When Need Low-level Execution Tracing

When fine-grained flow diagnostics are useful:

logger.trace("entered reconciliation step")

In this example, trace intent is explicit and concise.

When Attach Structured Trace Context

When a trace event should include fields:

logger.trace("cache probe", fields=[field("key", "user:42")])

In this example, trace output stays lightweight while still carrying structured detail.

And any shared context already carried by the logger still participates through the sink pipeline.

The write still uses the logger's stored target because this shortcut does not take a one-off target= override.

Error Case

e.g.:

• If the logger minimum level is above Trace, the call returns without writing a record.

• If a per-call target override is required, this helper is too narrow and log(...) should be used instead.

Notes

1. Prefer this helper when trace intent is clearer than a raw log(Level::Trace, ...) call.

2. Very verbose trace logging can become expensive even in a synchronous pipeline.