Logforth is a versatile, extensible, and easy-to-use logging framework for Rust applications. It allows you to configure multiple dispatches, filters, and appenders to customize your logging setup according to your needs.

Add log and logforth to your Cargo.toml:

cargo add log
cargo add logforth -F starter-log

Set up a basic logger that outputs to stdout:

fn main() {
    logforth::starter_log::stdout().apply();

    log::error!("This is an error message.");
    log::info!("This is an info message.");
    log::debug!("This debug message will not be printed by default.");
}

By default, all logging except the error level is disabled. You can enable logging at other levels by setting the RUST_LOG environment variable. For example, RUST_LOG=all cargo run will print all logs.

Configure multiple dispatches with different filters and appenders:

fn main() {
    logforth::starter_log::builder()
        .dispatch(|d| d
            .filter(LevelFilter::MoreSevereEqual(Level::Error))
            .append(append::Stderr::default()))
        .dispatch(|d| d
            .filter(LevelFilter::MoreSevereEqual(Level::Info))
            .append(append::Stdout::default()))
        .apply();

    log::error!("This error will be logged to stderr.");
    log::info!("This info will be logged to stdout.");
    log::debug!("This debug message will not be logged.");
}

Configure OpenTelemetry appender to export logs to an OpenTelemetry backend (full example):

fn main() {
    let static_diagnostic = {
        let mut static_diagnostic = StaticDiagnostic::default();
        static_diagnostic.insert("node_id", node_id);
        static_diagnostic.insert("nodegroup", nodegroup);
        static_diagnostic
    };

    let runtime = async_runtime();
    let filter = make_rust_log_filter(&opentelemetry.filter);
    let appender = runtime.block_on(async {
        let exporter = opentelemetry_otlp::LogExporter::builder()
            .with_tonic()
            .with_endpoint(&opentelemetry.otlp_endpoint)
            .with_protocol(opentelemetry_otlp::Protocol::Grpc)
            .build()
            .expect("failed to initialize opentelemetry logger");

        append::opentelemetry::OpentelemetryLogBuilder::new(service_name, exporter)
            .label("service.name", service_name)
            .build()
    });

    logforth::starter_log::builder()
        .dispatch(|b| {
            b.filter(filter)
                .diagnostic(FastraceDiagnostic::default())
                .diagnostic(static_diagnostic)
                .append(appender)
        })
        .apply();
}

Read more demos under the examples directory.

Logforth supports multiple dispatches, each with its own set of filters and appenders. This allows you to route log messages to different destinations based on their severity or other criteria.

A simple application may only need one dispatch, while a more complex application can have multiple dispatches for different modules or components.

Logforth supports a wide range of built-in appenders implemented as separate crates.

• Stdout and Stderr appenders for console logging.
• File appender for logging to optionally rolling files.
• OpentelemetryLog appender for exporting logs to OpenTelemetry backends.
• Testing appender that writes log records that can be captured by a test harness.
• FastraceEvent appender that writes log records to the Fastrace tracing system.
• Async combiner appender that makes another appender asynchronous.
• Syslog and Journald appenders for logging to system log services.

Users can also create their own appenders by implementing the Append trait.

Some appenders support customizable layouts for formatting log records. Logforth provides several built-in layouts:

• TextLayout formats log records as optionally colored text.
• JsonLayout formats log records as JSON objects.
• LogfmtLayout formats log records in the logfmt style.
• GoogleCloudLoggingLayout formats log records for Google Cloud Logging.

Users can also create their own layouts by implementing the Layout trait.

The following appenders do not use layouts:

• Async appender simply forwards log records to another appender; layouts are determined by the inner appender.
• FastraceEvent appender converts log records into tracing events; layouts are not applicable.
• OpentelemetryLog appender uses MakeBody trait for converting log records into OpenTelemetry log bodies. The MakeBody trait is more flexible and may optionally use a Layout implementation internally.

Logforth supports filtering log records at the dispatch level. Log records that do not pass the filters will not be sent to the appenders. Logforth provides several built-in filters:

• RustLogFilter allows you to configure logging levels and targets via the famous RUST_LOG directive pattern.

Users can also create their own filters by implementing the Filter trait.

Logforth supports providing a mapped diagnostic context (MDC) for stamping each log request.

• StaticDiagnostic allows you to set static key-value pairs for the entire application, like application version or hostname.
• ThreadLocalDiagnostic allows you to set thread-local key-value pairs.
• TaskLocalDiagnostic allows you to set task-local key-value pairs for async tasks.
• FastraceDiagnostic integrates with the Fastrace tracing system to provide tracing context (TraceId, SpanId, etc.) as diagnostics.

Users can also provide their own MDC by implementing the Diagnostic trait.

So far, Logforth provides out-of-the-box integration with the log crate. You can use Logforth as the backend for any crate that uses the log facade.

Read the online documents at https://docs.rs/logforth.

Components are organized into several crates:

• Core APIs: logforth-core
  • Built-in appenders: Stdout, Stderr, Testing
  • Built-in filters: LevelFilter
  • Built-in layouts: PlainTextLayout
  • Built-in diagnostics: StaticDiagnostic, ThreadLocalDiagnostic
• Appenders: logforth-append-*
  • logforth-append-async
  • logforth-append-fastrace
  • logforth-append-file
  • logforth-append-journald
  • logforth-append-opentelemetry
  • logforth-append-syslog
• Layouts: logforth-layout-*
  • logforth-layout-google-cloud-logging
  • logforth-layout-json
  • logforth-layout-logfmt
  • logforth-layout-text
• Filters: logforth-filter-*
  • logforth-filter-rustlog
• Diagnostics: logforth-diagnostic-*
  • logforth-diagnostic-fastrace
  • logforth-diagnostic-task-local
• Bridges: logforth-bridge-*
  • logforth-bridge-log

This crate is built against the latest stable release, and its minimum supported rustc version is 1.91.0.

The policy is that the minimum Rust version required to use this crate can be increased in minor version updates. For example, if Logforth 1.0 requires Rust 1.60.0, then Logforth 1.0.z for all values of z will also require Rust 1.60.0 or newer. However, Logforth 1.y for y > 0 may require a newer minimum version of Rust.

This crate has been in development since 2024-08. It is being used in several production systems stable enough to be considered mature, but it is still evolving.

All modular components are factored out into separate crates. We are working to stabilize the core APIs and several core components, and then release them as logforth-core 1.0. Other components will be released as separate crates that depend on logforth-core.

This project is licensed under Apache License, Version 2.0.

The name Logforth comes from an antonym of the Logback project, and may also be read as a homophone of "log force".