Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sebastienrousseau/rlg
A Rust library that implements application-level logging with a simple, readable output format 🦀
https://github.com/sebastienrousseau/rlg
Last synced: about 1 month ago
JSON representation
A Rust library that implements application-level logging with a simple, readable output format 🦀
- Host: GitHub
- URL: https://github.com/sebastienrousseau/rlg
- Owner: sebastienrousseau
- License: apache-2.0
- Created: 2023-12-05T12:11:11.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-09-16T12:47:19.000Z (about 2 months ago)
- Last Synced: 2024-09-16T14:52:53.063Z (about 2 months ago)
- Language: Rust
- Homepage: http://doc.rustlogs.com/
- Size: 1.81 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/funding.yml
- License: LICENSE-APACHE
- Code of conduct: .github/CODE-OF-CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Authors: AUTHORS.md
Awesome Lists containing this project
README
# RustLogs (RLG)
A robust and flexible Rust library for application-level logging with support for multiple formats and asynchronous operations.
[![Made With Love][made-with-rust]][00] [![Crates.io][crates-badge]][07] [![lib.rs][libs-badge]][03] [![Docs.rs][docs-badge]][08] [![Codecov][codecov-badge]][09] [![Build Status][build-badge]][10] [![GitHub][github-badge]][06]
## Overview
[`RustLogs (RLG)`][00] is a comprehensive Rust library that provides advanced application-level logging capabilities. It offers a wide range of logging APIs, helper macros, and flexible configuration options to simplify common logging tasks and meet diverse logging requirements.
## Features
- Multiple log levels: `ALL`, `DEBUG`, `DISABLED`, `ERROR`, `FATAL`, `INFO`, `NONE`, `TRACE`, `VERBOSE`, and `WARN`
- Structured log formats for easy parsing and filtering
- Support for multiple output formats including:
- Common Log Format (CLF)
- JavaScript Object Notation (JSON)
- Common Event Format (CEF)
- Extended Log Format (ELF)
- W3C Extended Log File Format
- Graylog Extended Log Format (GELF)
- Apache Access Log Format
- Logstash Format
- Log4j XML Format
- NDJSON (Newline Delimited JSON)
- Configurable logging destinations (file, stdout, network)
- Asynchronous logging for improved performance
- Log rotation support (size-based, time-based, date-based, count-based)
- Environment variable expansion in configuration
- Hot-reloading of configuration
- Comprehensive error handling and custom error types
## Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
rlg = "0.0.6"
```
## Documentation
For full API documentation, please visit [https://doc.rustlogs.com/][04] or [https://docs.rs/rlg][08].
## Rust Version Compatibility
Compiler support: requires rustc 1.56.0+
## Usage
### Basic Logging
```rust
use rlg::log::Log;
use rlg::log_format::LogFormat;
use rlg::log_level::LogLevel;
use rlg::utils::generate_timestamp;
// Create a new log entry
let log_entry = Log::new(
&vrd::random::Random::default().int(0, 1_000_000_000).to_string(),
&generate_timestamp(),
&LogLevel::INFO,
"MyComponent",
"This is a sample log message",
&LogFormat::JSON,
);
// Log the entry asynchronously
tokio::runtime::Runtime::new().unwrap().block_on(async {
log_entry.log().await.unwrap();
});
```
### Custom Log Configuration
```rust
use rlg::config::{Config, LogRotation, LoggingDestination};
use rlg::log::Log;
use rlg::log_format::LogFormat;
use rlg::log_level::LogLevel;
use std::path::PathBuf;
use std::num::NonZeroU64;
// Create a custom configuration
let mut config = Config::default();
config.log_file_path = PathBuf::from("/path/to/log/file.log");
config.log_level = LogLevel::DEBUG;
config.log_rotation = Some(LogRotation::Size(NonZeroU64::new(10_000_000).unwrap())); // 10 MB
config.logging_destinations = vec![
LoggingDestination::File(PathBuf::from("/path/to/log/file.log")),
LoggingDestination::Stdout,
];
// Create a new log entry with custom configuration
let log_entry = Log::new(
&vrd::random::Random::default().int(0, 1_000_000_000).to_string(),
&generate_timestamp(),
&LogLevel::INFO,
"MyComponent",
"This is a sample log message",
&LogFormat::JSON,
);
// Log the entry asynchronously
tokio::runtime::Runtime::new().unwrap().block_on(async {
log_entry.log().await.unwrap();
});
```
## Configuration
RustLogs (RLG) provides a flexible configuration system. You can customize various aspects of logging behavior, including:
- Log file path
- Log level
- Log rotation settings
- Log format
- Logging destinations
- Environment variables
You can load configuration from a file or environment variables using the `Config::load_async` method.
## Error Handling
RustLogs (RLG) provides comprehensive error handling through the `RlgError` type. This allows for more specific error handling in your application:
```rust
use rlg::log::Log;
use rlg::log_format::LogFormat;
use rlg::log_level::LogLevel;
use rlg::error::RlgError;
// Create a new log entry
let log_entry = Log::new(
&vrd::random::Random::default().int(0, 1_000_000_000).to_string(),
&generate_timestamp(),
&LogLevel::INFO,
"MyComponent",
"This is a sample log message",
&LogFormat::JSON,
);
// Log the entry asynchronously and handle potential errors
tokio::runtime::Runtime::new().unwrap().block_on(async {
match log_entry.log().await {
Ok(_) => println!("Log entry successfully written"),
Err(RlgError::IoError(err)) => eprintln!("I/O error when logging: {}", err),
Err(RlgError::FormattingError(err)) => eprintln!("Formatting error: {}", err),
Err(err) => eprintln!("Error logging entry: {}", err),
}
});
```
## Macros
RustLogs (RLG) provides a set of convenient macros to simplify logging tasks:
- `macro_log!`: Creates a new log entry with specified parameters.
- `macro_info_log!`: Creates an info log with default session ID and format.
- `macro_warn_log!`: Creates a warning log.
- `macro_error_log!`: Creates an error log.
- `macro_trace_log!`: Creates a trace log.
- `macro_fatal_log!`: Creates a fatal log.
- `macro_log_to_file!`: Asynchronously logs a message to a file.
- `macro_print_log!`: Prints a log to stdout.
- `macro_set_log_format_clf!`: Sets the log format to CLF if not already defined.
- `macro_log_if!`: Conditionally logs a message based on a predicate.
- `macro_debug_log!`: Conditionally logs a debug message based on the `debug_enabled` feature flag.
- `macro_log_with_metadata!`: Logs a message with additional metadata.
Refer to the [documentation][08] for more details on how to use these macros.
## Examples
To run the examples, clone the repository and use the following command:
```shell
cargo run --example example_name
```
Replace `example_name` with the name of the example you want to run.
## License
The project is dual-licensed under the terms of both the MIT license and the Apache License (Version 2.0).
- [Apache License, Version 2.0][01]
- [MIT license][02]
## 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.
## Acknowledgements
A special thank you goes to the [Rust Reddit](https://www.reddit.com/r/rust/) community for providing a lot of useful knowledge and expertise.
[00]: https://rustlogs.com
[01]: http://www.apache.org/licenses/LICENSE-2.0
[02]: http://opensource.org/licenses/MIT
[03]: https://lib.rs/crates/rlg
[04]: https://doc.rustlogs.com/
[06]: https://github.com/sebastienrousseau/rlg
[07]: https://crates.io/crates/rlg
[08]: https://docs.rs/rlg
[09]: https://codecov.io/gh/sebastienrousseau/rlg
[10]: https://github.com/sebastienrousseau/rlg/actions?query=branch%3Amaster
[build-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/rlg/release.yml?branch=master&style=for-the-badge&logo=github "Build Status"
[codecov-badge]: https://img.shields.io/codecov/c/github/sebastienrousseau/rlg?style=for-the-badge&token=Q9KJ6XXL67&logo=codecov "Codecov"
[crates-badge]: https://img.shields.io/crates/v/rlg.svg?style=for-the-badge&color=fc8d62&logo=rust "Crates.io"
[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.6-orange.svg?style=for-the-badge "View on lib.rs"
[docs-badge]: https://img.shields.io/badge/docs.rs-rlg-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs "Docs.rs"
[github-badge]: https://img.shields.io/badge/github-sebastienrousseau/rlg-8da0cb?style=for-the-badge&labelColor=555555&logo=github "GitHub"
[made-with-rust]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust 'Made With Rust'