Struct Logger 

pub struct Logger { /* private fields */ }

A structured logger instance.

Implementations

impl Logger

pub fn new() -> Self

Creates a new logger with default settings.

pub fn with_options(opts: Options) -> Self

Creates a new logger with the given options.

pub fn set_level(&self, level: Level)

Sets the minimum log level.

pub fn level(&self) -> Level

Returns the current log level.

pub fn set_prefix(&self, prefix: impl Into<String>)

Sets the log prefix.

pub fn prefix(&self) -> String

Returns the current prefix.

pub fn set_report_timestamp(&self, report: bool)

Sets whether to report timestamps.

pub fn set_report_caller(&self, report: bool)

Sets whether to report caller location.

Performance Warning

When enabled, this captures a full stack backtrace on every log call, which is approximately 100-1000x slower than normal logging.

Configuration	Typical Latency	Use Case
Default (no caller)	~100 ns	Production
With caller	~100 μs	Debug only

Only enable during active debugging sessions. Do NOT enable in production.

A runtime warning will be emitted on the first log call with caller reporting enabled (unless suppressed via suppress_caller_warning).

pub fn suppress_caller_warning(&self)

Suppresses the runtime performance warning for caller reporting.

By default, when caller reporting is enabled, a warning is emitted to stderr on the first log call to alert developers about the significant performance overhead (~100-1000x slower).

Call this method to suppress the warning when you have intentionally enabled caller reporting and understand the performance implications.

Example

use charmed_log::Logger;

let logger = Logger::new();
logger.set_report_caller(true);
logger.suppress_caller_warning();
// No warning will be emitted on first log call
logger.info("debug message", &[]);

pub fn set_time_format(&self, format: impl Into<String>)

Sets the time format.

pub fn set_formatter(&self, formatter: Formatter)

Sets the formatter.

pub fn set_styles(&self, styles: Styles)

Sets the styles.

pub fn with_fields(&self, fields: &[(&str, &str)]) -> Self

Creates a new logger with additional fields.

This is the idiomatic Rust method name. For Go API compatibility, use with instead.

pub fn with(&self, fields: &[(&str, &str)]) -> Self

Creates a new logger with additional fields (Go API compatibility).

This method matches the Go log.With() API. It is equivalent to with_fields.

Example

use charmed_log::Logger;

let logger = Logger::new();
let ctx_logger = logger.with(&[("request_id", "abc123"), ("user", "alice")]);
ctx_logger.info("Processing request", &[]);

pub fn with_prefix(&self, prefix: impl Into<String>) -> Self

Creates a new logger with a different prefix.

pub fn with_error_handler<F>(self, handler: F) -> Self

where F: Fn(Error) + Send + Sync + 'static,

Sets an error handler for I/O failures during logging.

When writing log output fails (e.g., disk full, pipe closed, permission denied), the handler is called with the I/O error. This allows applications to respond appropriately instead of silently losing log messages.

Default Behavior

If no error handler is configured:

• First failure: A warning is printed to stderr (if available)
• Subsequent failures: Silent (to avoid infinite loops)

Example

use charmed_log::Logger;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::sync::Arc;

let error_count = Arc::new(AtomicUsize::new(0));
let counter = error_count.clone();

let logger = Logger::new().with_error_handler(move |err| {
    counter.fetch_add(1, Ordering::Relaxed);
    eprintln!("Log write failed: {}", err);
});

pub fn log(&self, level: Level, msg: &str, keyvals: &[(&str, &str)])

Logs a message at the specified level.

This method uses a single write lock for the entire operation (format + write) to ensure configuration consistency. The only exception is caller info capture, which happens inside formatting but is atomic with respect to the log entry.

pub fn debug(&self, msg: &str, keyvals: &[(&str, &str)])

Logs a debug message.

pub fn info(&self, msg: &str, keyvals: &[(&str, &str)])

Logs an info message.

pub fn warn(&self, msg: &str, keyvals: &[(&str, &str)])

Logs a warning message.

pub fn error(&self, msg: &str, keyvals: &[(&str, &str)])

Logs an error message.

pub fn fatal(&self, msg: &str, keyvals: &[(&str, &str)])

Logs a fatal message.

pub fn logf(&self, level: Level, format: &str, args: &[&dyn Display])

Logs a message with formatting.

pub fn debugf(&self, format: &str, args: &[&dyn Display])

Logs a debug message with formatting.

pub fn infof(&self, format: &str, args: &[&dyn Display])

Logs an info message with formatting.

pub fn warnf(&self, format: &str, args: &[&dyn Display])

Logs a warning message with formatting.

pub fn errorf(&self, format: &str, args: &[&dyn Display])

Logs an error message with formatting.

pub fn fatalf(&self, format: &str, args: &[&dyn Display])

Logs a fatal message with formatting.

Trait Implementations

impl Clone for Logger

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Logger

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Logger

fn default() -> Self

Returns the “default value” for a type.