acta

A customizable logging library for Rust

Installation

cargo add acta

The default feature set enables Unicode console output and file logging.

cargo add acta --features serde,compress,nerd,async

Quick start

use acta::{init_tracing, LoggingConfig, Result};

fn main() -> Result<()> {
    let _guard = init_tracing(&LoggingConfig::default())?;

    tracing::info!("Hello, acta!");
    tracing::debug!(user = "alice", "User logged in");

    Ok(())
}

Keep the returned guard alive for as long as logging is needed. Dropping it stops file logging.

Features

If you disable default features, init_tracing is unavailable unless the file feature is enabled.

Configuration

LoggingConfig::default() uses:

• Level: LogLevel::Info
• Console: enabled with LogFormat::Compact
• Console writer: ConsoleWriter::Stdout
• ANSI colors: enabled
• Path and span display: enabled
• File logging: disabled

use acta::{
    init_tracing, ConsoleConfig, ConsoleWriter, LogFormat, LogLevel, LoggingConfig, Result,
};

fn main() -> Result<()> {
    let config = LoggingConfig {
        level: LogLevel::Debug,
        console: Some(ConsoleConfig {
            format: LogFormat::Compact,
            ansi: true,
            writer: ConsoleWriter::Stdout,
            show_path: true,
            show_spans: true,
            time_format: Some("%Y-%m-%d %H:%M:%S".to_string()),
        }),
        file: None,
    };

    let _guard = init_tracing(&config)?;

    Ok(())
}

Console formats

File logging

File logging is available with the file feature, which is enabled by default. File logs are written as flattened JSON events.

use acta::{
    init_tracing, ConsoleConfig, FileLoggingConfig, LogLevel, LogRotation, LoggingConfig, Result,
};
use std::path::PathBuf;

fn main() -> Result<()> {
    let config = LoggingConfig {
        level: LogLevel::Info,
        console: Some(ConsoleConfig::default()),
        file: Some(FileLoggingConfig {
            path: PathBuf::from("logs/app.log"),
            rotation: LogRotation::Rename,
        }),
    };

    let _guard = init_tracing(&config)?;

    Ok(())
}

Supported rotation modes:

acta uses tracing-subscriber EnvFilter directive syntax for startup filters and runtime reloads.

use acta::{FilterDirective, LogLevel, LoggingConfig};

let config = LoggingConfig {
level: LogLevel::Custom(FilterDirective::new(
"info,my_crate=debug,my_crate::db=trace",
)),
..Default::default ()
};

You can change filters after initialization through ReloadHandle.

use acta::{init_tracing, LogFilter, LogLevel, LoggingConfig, Result};

fn main() -> Result<()> {
    let guard = init_tracing(&LoggingConfig::default())?;

    guard.reload_handle.set_level(LogLevel::Debug)?;
    guard
        .reload_handle
        .set_target_level("my_crate", LogLevel::Trace)?;
    guard.reload_handle.remove_target_level("my_crate")?;
    guard.reload_handle.reload("info,my_crate=trace")?;
    guard.reload_handle.set_filter(
        LogFilter::new(LogLevel::Warn).with_target_level("my_crate", LogLevel::Debug),
    )?;

    Ok(())
}

RUST_LOG is not read automatically. If you want to use it, pass its value into LogLevel::Custom.

use acta::{FilterDirective, LogLevel, LoggingConfig};

let directive = std::env::var("RUST_LOG").unwrap_or_else( | _ | "info".to_string());
let config = LoggingConfig {
level: LogLevel::Custom(FilterDirective::new(directive)),
..Default::default ()
};

Custom formatter

AnsiFormatter powers LogFormat::Compact and can be customized through builder methods.

use acta::{AnsiFormatter, Icons, LevelLabels, Theme};

let formatter = AnsiFormatter::new()
.with_theme(Theme::tokyo_night())
.with_icons(Icons::unicode())
.with_labels(LevelLabels::long())
.with_time_format("%H:%M:%S")
.with_path_width(40)
.with_show_path(true)
.with_show_spans(true);

The default path width is generated at build time. Override it per formatter with AnsiFormatter::with_path_width.

Themes

Icons and labels

use acta::{Icons, LevelLabels};

let unicode_icons = Icons::unicode();
let short_labels = LevelLabels::short();
let long_labels = LevelLabels::long();

With the nerd feature enabled:

use acta::Icons;

let nerd_icons = Icons::nerd();

Runtime style reload

ReloadHandle can reload themes, icons, and labels only when it is created with a shared StyleConfig. init_tracing configures runtime filter reloads, but not runtime style reloads.

For style reloads, build the subscriber manually:

use acta::{
    build_console_layer_with, build_reload_filter, AnsiFormatter, ConsoleConfig, LogLevel, Result,
    Theme,
};
use tracing_subscriber::prelude::*;

fn main() -> Result<()> {
    let formatter = AnsiFormatter::new().with_theme(Theme::monokai());
    let style = formatter.style_config();
    let console_layer = build_console_layer_with(&ConsoleConfig::default(), formatter);
    let (filter_layer, reload_handle) = build_reload_filter(&LogLevel::Info, Some(style));

    let subscriber = tracing_subscriber::registry()
        .with(console_layer)
        .with(filter_layer);
    tracing::subscriber::set_global_default(subscriber)?;

    reload_handle.set_theme(Theme::dracula())?;

    Ok(())
}

This low-level setup requires adding tracing-subscriber as a direct dependency.

Async console writers

With custom-async, native-async, or async, ConsoleWriter gains async stdout and stderr variants.

AsyncWriterMode::Custom uses Tokio, so your application must run inside a Tokio runtime. If you use #[tokio::main], add Tokio as a direct dependency with the required runtime and macro features.

use acta::{
    init_tracing, AsyncWriterMode, ConsoleConfig, ConsoleWriter, LoggingConfig, Result,
};

#[tokio::main]
async fn main() -> Result<()> {
    let config = LoggingConfig {
        console: Some(ConsoleConfig {
            writer: ConsoleWriter::AsyncStdout(AsyncWriterMode::Custom),
            ..Default::default()
        }),
        ..Default::default()
    };

    let _guard = init_tracing(&config)?;

    Ok(())
}

AsyncWriterMode::Native uses tracing-appender non-blocking writers.