BitLogger/docs/api/global-trace.md

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

name	group	category	update-time	description	key-word
global-trace	api	global	20260512	Emit a trace-level record through the shared default logger shortcut.	global trace default public

Global-trace

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

Interface

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

input

• message : String - Trace message text.
• fields : Array[Field] - Optional structured fields attached to the record.

output

• Unit - No return value. The record is handled through the shared default logger.

Explanation

Detailed rules explaining key parameters and behaviors

• This helper delegates to default_logger().trace(...).
• Trace is the lowest built-in severity and is commonly disabled unless the shared minimum level is lowered.
• The shared default target and console sink are used.
• This helper favors convenience over explicit per-component logger ownership.

How to Use

Here are some specific examples provided.

When Need Quick Global Trace Output

When a script or small app wants temporary low-level diagnostics:

set_default_min_level(Level::Trace)
trace("entered sync loop")

In this example, the shared global path begins accepting trace records.

When Attach Structured Trace Context

When a global trace event should carry fields:

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

In this example, the global helper still supports structured metadata.

Error Case

e.g.:

• If the shared minimum level is above Trace, the record is skipped.

• If you need per-call target control, use an explicit Logger instead of this helper.

Notes

1. Global trace logging is convenient for scripts but easy to overuse in larger systems.

2. This helper always goes through the shared default logger path.