BitLogger/docs/api/logger.md

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

name	group	category	update-time	description	key-word
logger	api	logging	20260613	Public synchronous logger root type used for typed logging pipelines and sink-preserving composition.	logger sync type public

Logger

Logger[S] is the public synchronous root logger type. It stores a concrete sink type S together with minimum level, default target, and timestamp settings, then serves as the base value for typed composition helpers and write APIs.

Interface

pub struct Logger[S] {
  min_level : Level
  sink : S
  target : String
  timestamp : Bool
}

output

• Logger[S] - Public synchronous logger value parameterized by the concrete sink type S.

Explanation

Detailed rules explaining key parameters and behaviors

• This is a public root struct, not a type alias.
• The current fields are min_level : Level, sink : S, target : String, and timestamp : Bool.
• The sink type parameter is preserved across composition, which is why helpers such as with_context_fields(...), with_filter(...), with_patch(...), and with_queue(...) can return more specific logger shapes.
• The root logger also preserves the core target contract used across the sync API surface: log(..., target=...) can override the target for one call, while fixed-level helpers such as trace(...), debug(...), info(...), warn(...), and error(...) continue using the stored logger target unless code derives another logger first with with_target(...) or child(...).
• Logger::new(...) constructs this type as the main synchronous entry point.
• This root type is also what sits underneath both facade families: ApplicationLogger is a direct alias over the configured Logger[RuntimeSink] line, while LibraryLogger[S] is a narrowing wrapper around a Logger[S] value.

How to Use

Here are some specific examples provided.

When Need A Typed Root Logger Value

When synchronous logging should begin from a concrete sink-preserving root object:

let logger : Logger[ConsoleSink] = Logger::new(console_sink(), target="app")

In this example, the root logger keeps the concrete console sink type visible for later typed composition.

When Need A One-call Target Override On The Root Logger

When sync code should keep one logger value but emit a single record under a different target:

logger.log(Level::Error, "boom", target="app.audit")

In this example, the emitted record uses app.audit only for that one call.

And later trace(...), debug(...), info(...), warn(...), or error(...) calls still use the logger's stored target unless code derives another logger first with with_target(...) or child(...).

When Need To Build A Composed Logging Pipeline

When code should start from one root logger and then derive more specific wrapped forms:

let logger = Logger::new(console_sink(), min_level=Level::Info)
  .with_timestamp()
  .with_context_fields([field("service", "billing")])

In this example, the root type becomes the stable base for later logging behavior changes.

Error Case

e.g.:

• Logger[S] itself does not have a runtime failure mode.

• Actual write behavior still depends on the wrapped sink S, so sink-specific limitations remain unchanged behind the logger type.

Notes

1. Use Logger::new(...) when you need a value of this type in code.

2. Use ConfiguredLogger when config-built runtime helpers should stay directly available on the returned logger value.

3. Use ApplicationLogger when application code wants that same configured-runtime surface under an app-facing alias.

4. Use LibraryLogger[S] when a library boundary should intentionally narrow the public logger surface and expose broader composition only through to_logger().