logged-stream

Transparent logging wrapper for any synchronous or asynchronous Rust IO stream — inspect every byte, error, and lifecycle event that passes through.

• Description
• Usage
• Quick start
• Example
• Record kinds
• Architecture
• Provided implementations
  • Formatters (BufferFormatter)
  • Filters (RecordFilter)
  • Loggers (Logger)
• Custom implementations
• Use cases
• License
• Contribution

Description

logged-stream provides a single wrapper type, LoggedStream, that wraps any underlying IO object and logs every read, write, error, shutdown and drop that passes through it — without changing the code on either side. Because it re-implements the same IO trait it wraps, it drops straight into existing synchronous or asynchronous code.

• Drop-in. Same trait in, same trait out — wrapping a stream leaves the surrounding code unchanged.
• Sync and async. Works with std::io Read/Write streams and tokio AsyncRead/AsyncWrite streams alike.
• Replaceable parts. Formatting, filtering and log output are each a public trait — use a built-in, or implement the trait yourself if none fits your needs.
• Small and safe. A small dependency set and no unsafe code.

LoggedStream is deliberately a skeleton: it wires together four replaceable parts — the IO object you wrap, plus a formatter, a filter and a logger. Each event flows through them as event -> Formatter -> Filter -> Logger; see Architecture for how they fit together, and Custom implementations to write your own.

Usage

Add logged-stream to your Cargo.toml:

[dependencies]
logged-stream = "0.8"

or run:

$ cargo add logged-stream@0.8

It requires Rust 1.85.1 or newer (Rust 2024 edition).

Quick start

LoggedStream::new takes the stream to wrap plus the three pluggable parts — a formatter, a filter, and a logger. The snippet below wraps an in-memory Cursor (standing in for a socket or file, so it runs with no external setup), renders bytes as lowercase hexadecimal, keeps every record with DefaultFilter, and prints them through ConsoleLogger:

use log::LevelFilter;
use logged_stream::ConsoleLogger;
use logged_stream::DefaultFilter;
use logged_stream::LoggedStream;
use logged_stream::LowercaseHexadecimalFormatter;
use std::io::Cursor;
use std::io::Read;

fn main() {
    // ConsoleLogger forwards records to the `log` facade; env_logger prints them.
    env_logger::builder()
        .filter_level(LevelFilter::Debug)
        .format_timestamp_millis()
        .init();

    let mut stream = LoggedStream::new(
        Cursor::new(vec![0xde, 0xad, 0xbe, 0xef]),
        LowercaseHexadecimalFormatter::new_default(),
        DefaultFilter,
        ConsoleLogger::new_unchecked("debug"),
    );

    let mut buf = [0u8; 4];
    stream.read_exact(&mut buf).unwrap();
}

Running it logs the read, then the drop when stream goes out of scope:

[2026-01-01T12:00:00.000Z DEBUG logged_stream::logger] < de:ad:be:ef
[2026-01-01T12:00:00.000Z DEBUG logged_stream::logger] x Deallocated.

To see any output you also need env_logger and log in your Cargo.toml: ConsoleLogger only forwards records to the log facade, and any backend works.

See Provided implementations for the full set of formatters, filters and loggers you can swap in.

Example

A more realistic case: wrapping a std::net::TcpStream connected to an echo server. Each write_all logs a > record and each read_exact logs a < record, so both directions of the exchange are visible.

use log::LevelFilter;
use logged_stream::ConsoleLogger;
use logged_stream::DefaultFilter;
use logged_stream::LoggedStream;
use logged_stream::LowercaseHexadecimalFormatter;
use std::io::Read;
use std::io::Write;
use std::net::TcpStream;

fn main() {
    env_logger::builder()
        .filter_level(LevelFilter::Debug)
        .format_timestamp_millis()
        .init();

    // Assumes an echo server is listening on 127.0.0.1:8080 (the full example starts one).
    let mut client = LoggedStream::new(
        TcpStream::connect("127.0.0.1:8080").unwrap(),
        LowercaseHexadecimalFormatter::new_default(),
        DefaultFilter,
        ConsoleLogger::new_unchecked("debug"),
    );

    let send = [0x01, 0x02, 0x03, 0x04];
    client.write_all(&send).unwrap();
    let mut response = [0u8; 4];
    client.read_exact(&mut response).unwrap();

    let send = [0x05, 0x06, 0x07, 0x08];
    client.write_all(&send).unwrap();
    let mut response = [0u8; 4];
    client.read_exact(&mut response).unwrap();
}

Output to console:

[2026-01-01T12:00:00.000Z DEBUG logged_stream::logger] > 01:02:03:04
[2026-01-01T12:00:00.000Z DEBUG logged_stream::logger] < 01:02:03:04
[2026-01-01T12:00:00.000Z DEBUG logged_stream::logger] > 05:06:07:08
[2026-01-01T12:00:00.000Z DEBUG logged_stream::logger] < 05:06:07:08
[2026-01-01T12:00:00.000Z DEBUG logged_stream::logger] x Deallocated.

The snippets above are condensed. Full runnable versions live in the examples/ directory:

• tcp-stream-console-logger.rs — the synchronous example above, together with the echo server.
• tokio-tcp-stream-console-logger.rs — the same over tokio's asynchronous API.
• file-logger.rs — writing records to a file instead of the console.
• shared-file-logger.rs — several concurrent connections logging into one shared file, each tagged with its own prefix, and why append mode is what makes that safe.
• composite-filters.rs — combining filters with AllFilter / AnyFilter.

Full API documentation is on docs.rs.

Record kinds

Every log line begins with a single character identifying the kind of event:

Every kind except Open is produced automatically. Open is a marker you record yourself with LoggedStream::log_open — for example stream.log_open(format!("Established connection with {peer}")) right after a connection is established. Like any record, it passes through the filter, so a RecordKindFilter that omits Open will suppress it.

Architecture

LoggedStream<S, Formatter, Filter, L> is generic over four independent, pluggable parts. Each logged event flows through them in order:

event  ->  Formatter  ->  Filter  ->  Logger

• The inner IO object (S). The stream you are wrapping. Any type implementing Read/Write (or the tokio async equivalents) works — a socket, a file, an in-memory buffer, or your own type. LoggedStream implements the same IO trait S does, so it slots in wherever S was used.
• Formatter (BufferFormatter). Turns the read and written byte buffers into the display strings you see in the log.
• Filter (RecordFilter). Decides which records are logged. It runs on every record kind, including Shutdown and Drop.
• Logger (Logger). The sink that consumes accepted records.

All three of BufferFormatter, RecordFilter and Logger are public, Send + 'static and object-safe, with blanket implementations for Box<...> (and Arc<T> where T: Sync for BufferFormatter). You are free to supply your own implementation of any part and select one at runtime as a trait object — see Custom implementations.

Provided implementations

Formatters (BufferFormatter)

Control how byte buffers are rendered. Each formatter stores a separator (default :) and exposes parallel constructors: new, new_static, new_owned and new_default.

Filters (RecordFilter)

Decide which records reach the logger.

Loggers (Logger)

Consume each accepted record.

ConsoleLogger and FileLogger additionally accept an optional prefix (with_prefix / set_prefix, none by default), written verbatim before the record kind character of every line. It tells apart several LoggedStreams — for example one per connection — that share a single console or file:

[2026-07-20T12:34:56Z] [conn 5] > 01:02:03:04
[2026-07-20T12:34:56Z] [conn 7] < 05:06:07:08

To let several FileLoggers write to one file, construct them with FileLogger::open, which opens the file in append mode. Each record is rendered up front and written with a single write_all call, so concurrent loggers never interleave parts of a line. Passing independently opened non-append files (for example from File::create) instead gives each logger its own starting offset, and they will silently overwrite each other's records.

If none of the provided implementations matches your requirements, you can implement the corresponding trait yourself and pass your type to LoggedStream exactly like a built-in.

Custom implementations

LoggedStream is deliberately a skeleton: three of its four parts are defined by public traits, and everything this crate ships is an ordinary implementation of one of them.

All three are Send + 'static and object-safe, so you can box them (Box<dyn BufferFormatter>) and choose an implementation at runtime. The fourth part needs no trait from this crate at all — anything implementing std::io::Read/Write or the tokio async equivalents can be wrapped, including your own types.

For example, a formatter that renders printable bytes as ASCII — handy for text protocols, which the built-in numeric formatters do not cover:

use logged_stream::BufferFormatter;

struct AsciiFormatter;

impl BufferFormatter for AsciiFormatter {
    fn get_separator(&self) -> &str {
        ""
    }

    fn format_byte(&self, byte: &u8) -> String {
        if byte.is_ascii_graphic() || *byte == b' ' {
            (*byte as char).to_string()
        } else {
            String::from(".")
        }
    }
}

Every record a Logger receives is a Record carrying a kind, a message and a time, so a custom logger can route by record kind, re-timestamp, or forward to any sink you like.

Use cases

LoggedStream hands you a formatted, filterable, timestamped record of every read, write, error, shutdown, and drop that crosses a stream — without changing the code on either side of it. That makes it a building block for a range of tools and diagnostics. A few examples of what you can build:

• Network traffic monitoring — wrap a TcpStream (synchronous or asynchronous) to record every byte a client and server exchange, for debugging protocols, tracking data flow, or auditing what actually crossed the wire.
• I/O debugging — see the exact bytes moving through a file, socket, or any custom stream, alongside the errors, shutdowns, and drops around them, to pin down data corruption or where a connection unexpectedly closed.
• Protocol and application-traffic capture — log the raw wire traffic of a protocol you are implementing or reverse-engineering, such as a database driver, an RPC channel, or a custom binary format. LoggedStream captures the bytes; decode or parse them downstream if you need higher-level detail like SQL statements.
• Timing and throughput diagnostics — every record is timestamped, so you can layer your own cadence, gap, and throughput analysis on top: when reads and writes happened and how much data moved. (The timestamps are yours to correlate — the library does not measure per-call latency itself.)
• Transparent proxies and audit trails — build a man-in-the-middle proxy or an audit log that relays traffic unchanged while recording it. The author's logged_tcp_proxy does exactly this: it wraps each TcpStream, splits it into read/write halves, and prints every connection's payload. Route the records to a file, memory, or a channel through the pluggable loggers to keep a durable trail.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.