Build-library-logger

Build a LibraryLogger[RuntimeSink] from LoggerConfig. This facade keeps a smaller library-oriented sync surface while still using config-driven runtime assembly underneath.

Interface

pub fn build_library_logger(config : LoggerConfig) -> LibraryLogger[RuntimeSink] {

input

• config : LoggerConfig - Fully assembled sync logger config.

output

• LibraryLogger[RuntimeSink] - Library-facing logger wrapper over the configured runtime sink.

Explanation

Detailed rules explaining key parameters and behaviors

• This API builds a configured runtime logger first and then wraps that same value as LibraryLogger[RuntimeSink].
• The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application.
• The returned facade wraps the same underlying ConfiguredLogger value that build_logger(...) would produce directly.
• The facade intentionally exposes a smaller logging surface than the full configured runtime logger.
• In particular, the configured runtime helper surface is preserved rather than rebuilt, but it is intentionally not directly exposed on the returned facade. Queue metrics, flush or drain helpers, and file controls stay behind to_logger() instead of disappearing.
• The facade still preserves the underlying logger target rules on its exposed write methods: log(..., target=...) can override the target for one write, while info(...), warn(...), and error(...) continue using the stored logger target unless the facade first derived another logger with with_target(...) or child(...).
• Queue metrics, flush and drain helpers, and file runtime controls remain on the underlying ConfiguredLogger, not on the returned facade itself.
• Call to_logger() if a caller must recover the underlying full logger object.
• Use this builder when the boundary should preserve the configured runtime logger path but still hide broader runtime helper methods from downstream callers.

How to Use

Here are some specific examples provided.

When Need A Smaller Library-facing Logging Type

When package code should accept or produce a narrower logger facade:

let logger = build_library_logger(
  LoggerConfig::new(target="lib", sink=SinkConfig::new(kind=SinkKind::Console)),
)

In this example, the logger is built from config and then narrowed to the library facade.

When Need Runtime Helpers After Library-oriented Construction

When config-built runtime queue or file controls are still needed internally:

let logger = build_library_logger(config)
let full = logger.to_logger()
ignore(full.sink.pending_count())

In this example, the library facade is unwrapped before using runtime-specific helpers through the preserved RuntimeSink value.

And the unwrapped value still carries the same RuntimeSink pipeline built from the original config.

And unlike ApplicationLogger, the narrower builder result does not expose those runtime helpers directly on the facade surface.

When Need A Per-call Target Override Through The Library Builder Facade

When typed library config should still build a facade that allows a one-write target override without unwrapping first:

let logger = build_library_logger(config)
logger.log(Level::Error, "boom", target="lib.audit")

In this example, the emitted record uses lib.audit for that write.

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

Error Case

e.g.:

• If backend-specific sink limitations exist, they still apply after the facade is built.

• If code later needs queue metrics, flush or drain helpers, or file runtime controls, it must unwrap with to_logger().

Notes

1. Prefer this facade when library APIs should not expose the full configured runtime logger type.

2. Use parse_and_build_library_logger(...) when starting from JSON text.

3. Use to_logger() when internal code later needs broader logger composition or direct access to the preserved RuntimeSink value without changing the public facade type.