Crate lightbench 

Lightbench - A transport-agnostic benchmarking framework.

This crate provides foundational components for building high-performance benchmarks measuring latency, throughput, and reliability metrics.

Features

• Runner: High-level Benchmark builder with automatic rate distribution
• Metrics: HDR histogram-based latency tracking with atomic counters
• Rate Control: Token bucket rate limiter for open-loop benchmarks
• Output: Async CSV and stdout writers for metric snapshots

Quick Start

use lightbench::{Benchmark, WorkResult, now_unix_ns_estimate};
use lightbench::patterns::work::BenchmarkWork;

#[derive(Clone)]
struct NoopWork;

impl BenchmarkWork for NoopWork {
    type State = ();
    async fn init(&self) {}
    async fn work(&self, _: &mut ()) -> WorkResult {
        let start = now_unix_ns_estimate();
        // ... do work ...
        WorkResult::success(now_unix_ns_estimate() - start)
    }
}

let results = Benchmark::new()
    .rate(1000.0)      // Total rate, auto-split across workers
    .workers(4)
    .duration_secs(10)
    .work(NoopWork)
    .run()
    .await;

results.print_summary();

Modules

• patterns - Benchmark patterns (request, producer/consumer, async task)
• metrics - Statistics collection with HDR histograms
• rate - Rate limiting for controlled benchmarks
• time_sync - Fast timestamp utilities
• output - CSV/stdout output writers
• logging - Tracing initialization

Re-exports

pub use config::BenchmarkConfig;

pub use error::FrameworkError;

pub use metrics::errors::ErrorCounter;

pub use metrics::SequenceTracker;

pub use metrics::Stats;

pub use metrics::StatsSnapshot;

pub use output::OutputWriter;

pub use patterns::async_task::AsyncTaskBenchmark;

pub use patterns::producer_consumer::ProducerConsumerBenchmark;

pub use patterns::request::Benchmark;

pub use patterns::work::AsyncTaskResults;

pub use patterns::work::BenchmarkResults;

pub use patterns::work::BenchmarkSummary;

pub use patterns::work::BenchmarkWork;

pub use patterns::work::ConsumerRecorder;

pub use patterns::work::ConsumerWork;

pub use patterns::work::PollResult;

pub use patterns::work::PollWork;

pub use patterns::work::ProducerConsumerResults;

pub use patterns::work::ProducerWork;

pub use patterns::work::SubmitWork;

pub use patterns::work::WorkResult;

pub use rate::DynamicRateController;

pub use rate::RateController;

pub use rate::SharedRateController;

pub use time_sync::latency_ns;

pub use time_sync::now_unix_ns_estimate;

Modules

config

Configuration structs for benchmark runners.

error

Structured error types for the framework.

logging

Logging initialization.

metrics

Statistics collection with HDR histogram for latency tracking.

output

Output writing for metrics snapshots.

patterns

Benchmark patterns for common workload types.

rate

Rate limiting with token bucket algorithm.

time_sync

Fast time synchronization utilities.

Macros

tprintln

Like println! but prefixes every line with the elapsed time since the program started (e.g. [ 1.234s]), producing a scrolling log that the user can review as history.