BitLogger/docs/api/parse-and-build-logger.md

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

name	group	category	update-time	description	key-word
parse-and-build-logger	api	config	20260512	Parse logger JSON config and immediately build a runtime logger with a stable control surface.	config logger json public

Parse-and-build-logger

Parse a JSON logger definition and build a ready-to-use ConfiguredLogger. This is the most direct API when configuration is loaded from files, environment-derived JSON, or external settings systems.

Interface

pub fn parse_and_build_logger(input : String) -> ConfiguredLogger raise ConfigError {}

input

• input : String - JSON text following the supported LoggerConfig schema.

output

• ConfiguredLogger - A runtime logger with normal logging methods plus queue/file control helpers.

Explanation

Detailed rules explaining key parameters and behaviors

• Parsing and building are done in one step, which is useful when you do not need to inspect the intermediate LoggerConfig.
• The returned ConfiguredLogger is just Logger[RuntimeSink], so it still supports regular logging calls.
• Queue wrapping and file control helpers remain available after config assembly.
• Errors are surfaced as ConfigError rather than silent fallback.

How to Use

Here are some specific examples provided.

When Load Logger From JSON Text

When configuration comes from a file, environment variable, or settings service:

let logger = parse_and_build_logger(
  "{\"min_level\":\"info\",\"target\":\"api\",\"sink\":{\"kind\":\"text_console\"}}",
) catch {
  err => {
    ignore(err)
    return
  }
}

In this example, config parsing and logger construction happen in one place.

And the resulting value can immediately emit logs.

When Need Config-built File Or Queue Controls

When the sink shape is chosen by config but runtime introspection is still required:

let logger = parse_and_build_logger(raw) catch {
  err => return
}
ignore(logger.pending_count())
ignore(logger.file_runtime_state())

In this example, the configured runtime surface is still operational after building.

Error Case

e.g.:

• If input is not valid JSON, a ConfigError is raised.

• If supported keys have wrong types or unsupported enum text, a ConfigError is raised.

Notes

1. Use parse_logger_config_text(...) first if you want to validate and inspect config separately.

2. Prefer this API for app bootstrapping paths that read config once and then construct the runtime logger.