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.
• 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 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().