Struct LoggedStream 

pub struct LoggedStream<S: 'static, Formatter: 'static, Filter: RecordFilter + 'static, L: Logger + 'static> { /* private fields */ }

Wrapper for an IO object that logs every read, write, error, shutdown and drop that passes through it.

LoggedStream wraps an underlying IO object implementing the Read / Write traits, or their asynchronous tokio analogues AsyncRead / AsyncWrite, and logs all read and write operations, errors, shutdowns and drops. It re-implements the same IO trait it wraps, so it is a drop-in replacement that works transparently in both synchronous and asynchronous code.

Architecture

LoggedStream 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. 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.

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.

Formatter	Renders each byte as
LowercaseHexadecimalFormatter	lowercase hexadecimal — 0a:ff
UppercaseHexadecimalFormatter	uppercase hexadecimal — 0A:FF
DecimalFormatter	decimal — 10:255
OctalFormatter	octal — 012:377
BinaryFormatter	binary — 00001010:11111111

Filters (RecordFilter)

Decide which records reach the logger.

Filter	Behavior
DefaultFilter	Accepts every record.
RecordKindFilter	Accepts only the record kinds in an allow-list given at construction.
AllFilter	AND — a record passes only if every child filter accepts it (an empty list accepts everything).
AnyFilter	OR — a record passes if any child filter accepts it (an empty list rejects everything).

Loggers (Logger)

Consume each accepted record.

Logger	Destination
ConsoleLogger	Emits records through the log facade.
FileLogger	Writes records to a file.
MemoryStorageLogger	Retains recent records in a bounded in-memory buffer.
ChannelLogger	Sends records over an mpsc channel for handling elsewhere.

Implementations

impl<S: 'static, Formatter: 'static, Filter: RecordFilter + 'static, L: Logger + 'static> LoggedStream<S, Formatter, Filter, L>

pub fn new(stream: S, formatter: Formatter, filter: Filter, logger: L) -> Self

Construct a new instance of LoggedStream using provided arguments.

pub fn log_open(&mut self, message: impl Into<String>)

Emit a custom RecordKind::Open record carrying message.

RecordKind::Open is never produced automatically by the read, write, shutdown and drop machinery — this method is the way to emit one. Use it to annotate the start of a stream, for example to record the peer of a freshly established connection ("Established connection with 127.0.0.1:8080") or other per-stream metadata.

Like every other record, the Open record is passed through the filter before it reaches the logger, so a RecordKindFilter that does not allow Open will suppress it. The message is logged verbatim; it is not run through the formatter, which only applies to byte buffers.

For asynchronous streams, call this before splitting the wrapper with tokio::io::split, since the resulting halves do not expose it.

impl<S: 'static, Formatter: 'static, Filter: RecordFilter + 'static> LoggedStream<S, Formatter, Filter, MemoryStorageLogger>

pub fn get_log_records(&self) -> VecDeque<Record>

pub fn clear_log_records(&mut self)

impl<S: 'static, Formatter: 'static, Filter: RecordFilter + 'static> LoggedStream<S, Formatter, Filter, ChannelLogger>

pub fn take_receiver(&mut self) -> Option<Receiver<Record>>

pub fn take_receiver_unchecked(&mut self) -> Receiver<Record>

Trait Implementations

impl<S: AsyncRead + Unpin + 'static, Formatter: BufferFormatter + Unpin + 'static, Filter: RecordFilter + Unpin + 'static, L: Logger + Unpin + 'static> AsyncRead for LoggedStream<S, Formatter, Filter, L>

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl<S: AsyncWrite + Unpin + 'static, Formatter: BufferFormatter + Unpin + 'static, Filter: RecordFilter + Unpin + 'static, L: Logger + Unpin + 'static> AsyncWrite for LoggedStream<S, Formatter, Filter, L>

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from buf into the object.

fn poll_flush( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<S: Debug + 'static, Formatter: Debug + 'static, Filter: RecordFilter + Debug + 'static, L: Logger + Debug + 'static> Debug for LoggedStream<S, Formatter, Filter, L>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: 'static, Formatter: 'static, Filter: RecordFilter + 'static, L: Logger + 'static> Drop for LoggedStream<S, Formatter, Filter, L>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<S: Read + 'static, Formatter: BufferFormatter + 'static, Filter: RecordFilter + 'static, L: Logger + 'static> Read for LoggedStream<S, Formatter, Filter, L>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_, u8>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact( &mut self, cursor: BorrowedCursor<'_, u8>, ) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

fn read_le<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in little-endian order.

fn read_be<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in big-endian order.

impl<S: Write + 'static, Formatter: BufferFormatter + 'static, Filter: RecordFilter + 'static, L: Logger + 'static> Write for LoggedStream<S, Formatter, Filter, L>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Writes a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.