14 releases
0.4.0 | Jul 3, 2024 |
---|---|
0.3.5 | Feb 24, 2024 |
0.3.4 | Oct 7, 2023 |
0.3.2 | Jun 12, 2023 |
#99 in Debugging
115 downloads per month
Used in 2 crates
59KB
961 lines
logged-stream
Table of contents
Description
Structure
logged-stream
is a Rust library that provides a LoggedStream
structure which can be used as a wrapper for underlying IO object which implements std::io::Write
and std::io::Read
traits or their asynchronous analogues from tokio
library to enable logging of all read and write operations, errors and drop.
LoggedStream
structure constructs from four parts:
- Underlying IO object, which must implement
std::io::Write
andstd::io::Read
traits or their asynchronous analogues fromtokio
library:tokio::io::AsyncRead
andtokio::io::AsyncWrite
. - Buffer formatting part, which must implement
BufferFormatter
trait provided by this library. This part ofLoggedStream
is responsible for the form you will see the input and output bytes. Currently this library provides the following implementations ofBufferFormatter
trait:LowercaseHexadecimalFormatter
,UppercaseHexadecimalFormatter
,DecimalFormatter
,BinaryFormatter
andOctalFormatter
. AlsoBufferFormatter
is public trait so you are free to construct your own implementation. - Filtering part, which must implement
RecordFilter
trait provide by this library. This part ofLoggedStream
is responsible for log records filtering. Currently this library provides the following implementation ofRecordFilter
trait:DefaultFilter
which accepts all log records andRecordKindFilter
which accepts logs with kinds specified during construct. AlsoRecordFilter
is public trait and you are free to construct your own implementation. - Logging part, which must implement
Logger
trait provided by this library. This part ofLoggedStream
is responsible for further work with constructed, formatter and filtered log record. For example, it can be outputted to console, written to the file, written to database, written to the memory for further use or sended by the channel. Currently this library provides the following implementations ofLogger
trait:ConsoleLogger
,MemoryStorageLogger
,ChannelLogger
andFileLogger
. AlsoLogger
is public trait and you are free to construct your own implementation.
Use Cases
- Network Traffic Monitoring:
- Monitor and log all incoming and outgoing network traffic in a server or client application.
- Useful for debugging network protocols, tracking data exchange, and ensuring security compliance.
- Debugging I/O Operations:
- Log all read and write operations to diagnose issues with file or network I/O.
- Helps in identifying bottlenecks, data corruption, and unexpected behavior in I/O operations.
- Performance Analysis:
- Analyze the performance of I/O operations by logging the time taken for each read/write operation.
- Helps in identifying performance issues and optimizing I/O-intensive applications.
- Database Activity Logging:
- Log all interactions with a database, including queries, updates, and transaction details.
- Helps in database performance tuning, debugging query issues, and maintaining audit logs.
- Proxy Servers:
- Implement logging in proxy servers to monitor and log all forwarded traffic.
- Useful for debugging proxy behavior and ensuring proper data routing.
Usage
To use logged-stream
, add the following line to your Cargo.toml
:
[dependencies]
logged-stream = "0.4"
or run the following Cargo command in your project directory:
$ cargo add logged-stream@0.4
Example
This is a simple usage example of LoggedStream
structure with std::net::TcpStream
as underling IO object which connects to some echo-server, lowercase hexadecimal formatter, default filter and console logger.
fn main() {
env::set_var("RUST_LOG", "debug");
env_logger::init();
let mut client = LoggedStream::new(
net::TcpStream::connect("127.0.0.1:8080").unwrap(),
LowercaseHexadecimalFormatter::new(None),
DefaultFilter::default(),
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();
let send = [0x09, 0x0a, 0x0b, 0x0c];
client.write_all(&send).unwrap();
let mut response = [0u8; 4];
client.read_exact(&mut response).unwrap();
let send = [0x01, 0x02, 0x03, 0x04];
client.write_all(&send).unwrap();
let mut response = [0u8; 4];
client.read_exact(&mut response).unwrap();
}
Output to console:
[2023-04-18T08:18:45.895Z DEBUG logged_stream::logger] > 01:02:03:04
[2023-04-18T08:18:45.895Z DEBUG logged_stream::logger] < 01:02:03:04
[2023-04-18T08:18:45.895Z DEBUG logged_stream::logger] > 05:06:07:08
[2023-04-18T08:18:45.895Z DEBUG logged_stream::logger] < 05:06:07:08
[2023-04-18T08:18:45.895Z DEBUG logged_stream::logger] > 09:0a:0b:0c
[2023-04-18T08:18:45.896Z DEBUG logged_stream::logger] < 09:0a:0b:0c
[2023-04-18T08:18:45.896Z DEBUG logged_stream::logger] > 01:02:03:04
[2023-04-18T08:18:45.896Z DEBUG logged_stream::logger] < 01:02:03:04
[2023-04-18T08:18:45.896Z DEBUG logged_stream::logger] x Deallocated.
Full version of this example can be found there.
Same example, but rewritten using asynchronous API, can be found there.
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.
Dependencies
~3.5–9MB
~78K SLoC