tracing-setup

tracing-setup is a Rust crate that simplifies the configuration and usage of the tracing crate for instrumenting applications to collect structured, event-based diagnostic information. It provides utilities for buffered logging, dynamic tracing levels, file logging with rotation, and test logging setup functions.

Table of Contents

• Features
• Installation
• Usage
  • Buffered Logging
  • Dynamic Tracing Levels
  • File Logging Configuration
  • Test Logging Utilities
• Modules and Traits
• License

Features

• Buffered Logging: Collect tracing events in a buffer and flush them on demand.
• Dynamic Tracing Levels: Change the tracing level at runtime.
• File Logging: Log tracing events to files with optional rotation policies.
• Test Logging Utilities: Simplify logging setup in tests.

Installation

Add the following to your Cargo.toml:

[dependencies]
tracing-setup = "1.0.2"

Usage

Buffered Logging

Buffered logging allows you to collect tracing events in memory and flush them later. This is useful when you want to defer logging until a certain point in your application, such as after a transaction completes.

Setup Buffered Tracing

use tracing_setup::setup_buffered_tracing;
use tracing::{info, debug};
use tracing::subscriber::set_global_default;

let buffered_subscriber = setup_buffered_tracing(Some("my_tag"));

// Register the subscriber as the global default
set_global_default(buffered_subscriber.clone())
    .expect("Failed to set subscriber");

// Emit some tracing events
info!("This is an info message");
debug!("This is a debug message");

// Flush the buffered events
buffered_subscriber.flush();

Event Printers

Customize how events are printed when flushed by selecting an EventPrinter variant:

• EventPrinter::FullWithHeader: Prints the full event with headers.
• EventPrinter::LogLineAndContents: Prints the log line and contents.
• EventPrinter::JustTheContents: Prints only the event contents (default).

Example:

use tracing_setup::{setup_buffered_tracing, EventPrinter};
use tracing::subscriber::set_global_default;

let buffered_subscriber = setup_buffered_tracing(None);
buffered_subscriber.buffered_layer.event_printer = EventPrinter::LogLineAndContents;

set_global_default(buffered_subscriber.clone())
    .expect("Failed to set subscriber");

// Emit events and flush
// ...

Dynamic Tracing Levels

Adjust the tracing level at runtime using the setup_dynamic_tracing function.

use tracing_setup::setup_dynamic_tracing;
use tracing::{info, debug, Level};
use tracing_subscriber::EnvFilter;

let reload_handle = setup_dynamic_tracing(Level::INFO);

// Emit some tracing events
info!("This is an info message");
debug!("This debug message should NOT appear at INFO level");

// Change the tracing level to DEBUG at runtime
reload_handle.reload(EnvFilter::new("debug")).unwrap();

// Now debug messages will appear
debug!("This debug message should appear at DEBUG level");

File Logging Configuration

Configure file logging with optional rotation using FileLoggingConfiguration.

use tracing_setup::{FileLoggingConfiguration, init_file_logging};
use tracing::info;
use tracing_appender::rolling::Rotation;
use std::path::PathBuf;

// Configure file logging
let config = FileLoggingConfiguration::new(
    Some(PathBuf::from("app.log")), // Log file path
    tracing::Level::INFO,           // Log level
    Some(Rotation::DAILY),          // Rotation policy
);

// Initialize file logging
init_file_logging(config);

// Now, tracing events will be logged to "app.log" with daily rotation
info!("Application started");

Test Logging Utilities

Simplify logging setup in tests with init_test_logger.

use tracing_setup::init_test_logger;
use tracing::LevelFilter;
use tracing::info;

#[test]
fn my_test() {
    init_test_logger(LevelFilter::Debug, true);

    info!("This is an info message in a test");
}

Alternatively, use the setup_test_logger macro:

use tracing_setup::setup_test_logger;
use tracing::info;

#[test]
fn my_test() {
    setup_test_logger!();

    info!("This is an info message in a test");
}

Modules and Traits

BufferedLayer

A tracing subscriber layer that buffers events in memory and can flush them to an output. Useful for deferring logging until a specific point in your application.

Example

use tracing_setup::BufferedLayer;
use tracing_subscriber::layer::SubscriberExt;
use tracing_subscriber::Registry;

let buffered_layer = BufferedLayer::default();
let subscriber = Registry::default().with(buffered_layer.clone());

// Set the subscriber as the default
tracing::subscriber::set_global_default(subscriber)
    .expect("Failed to set subscriber");

// Emit events
tracing::info!("Event 1");
tracing::info!("Event 2");

// Flush events
buffered_layer.flush();

BufferedSubscriberLayer

A subscriber that wraps BufferedLayer and implements the Flushable trait.

Flushable Trait

Defines a flush method for types that can flush buffered events.

pub trait Flushable {
    fn flush(&self);
}

HandleBufferWriteEvent Trait

Handles writing events to the buffer in different formats.

Implementations:

• FullWithHeader: Prints full event details with headers.
• LogLineAndContents: Prints the log line and contents.
• JustTheContents: Prints only the event contents.

EventPrinter Enum

Specifies the format for printing events when flushing.

#[derive(Debug, Clone)]
pub enum EventPrinter {
    FullWithHeader,
    LogLineAndContents,
    JustTheContents,
}

FileLoggingConfiguration

Configures file logging with options for log path, level, rotation, and whether the log is temporary (deleted when the configuration is dropped).

Fields

• log_path: Option<PathBuf>: Path to the log file.
• log_level: Level: Logging level.
• rotation: Option<Rotation>: Log rotation policy.
• temporary: bool: Indicates if the log file should be deleted when dropped.

Methods

• new: Creates a new configuration.
• new_temporary: Creates a new temporary configuration.
• default: Provides default configuration.
• default_temporary: Provides default temporary configuration.
• create_writer: Creates a writer based on the configuration.

init_file_logging

Initializes file logging based on a FileLoggingConfiguration.

pub fn init_file_logging(config: FileLoggingConfiguration)

Utility Functions

• configure_tracing: Initializes the logging subscriber with environment filter.
• init_default_file_logging: Initializes file logging with default configuration.
• init_test_logger: Initializes a test logger with specified level.
• init_test_logger_with_max_level_filter: Initializes a test logger with maximum level filter.

License

This project is licensed under the MIT License.

Note: Ensure that all dependencies such as tracing, tracing_subscriber, tracing_appender, and colored are included in your Cargo.toml to use the features demonstrated in this README.

Feel free to contribute to this crate by opening issues or submitting pull requests.