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

Notes are here.

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.

3. ConfiguredLogger keeps queue and file helper methods, so config-driven logging does not lose control surface.

4. Keep the JSON schema limited to supported built-in sink shapes when designing external config files.