grlog 0.1.0

A high-performance async logging library based on gorust GMP runtime
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

# grlog

A high-performance async logging library based on gorust GMP runtime.

## Overview

`grlog` is a high-performance asynchronous logging library built on top of the `gorust` GMP runtime. It leverages Go-like concurrency models to provide efficient, non-blocking logging capabilities for Rust applications.

The library is designed to handle high-volume logging scenarios where traditional synchronous loggers might become bottlenecks. By utilizing gorust's lightweight goroutines and channels, `grlog` ensures logging doesn't block your main application threads.

## Features

- **Asynchronous**: Non-blocking logging that won't stall your application
- **High Performance**: Built on gorust GMP runtime for efficient concurrency
- **Flexible Configuration**: Support for multiple log targets and filtering
- **Environment Integration**: Compatible with standard RUST_LOG environment variable
- **Module-level Filtering**: Configure log levels per module
- **Multiple Output Targets**: Console (stdout/stderr), file, and other outputs supported
- **Timestamp Formatting**: Automatic timestamp with millisecond precision
- **Standard Compliant**: Implements the popular `log` crate traits

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
grlog = "0.1.0"
log = "0.4"
```

## Usage

### Basic Usage

```rust
use log::info;
use grlog::init;

fn main() {
    // Initialize with default settings (logs to stderr, level info)
    init();
    
    info!("This is an info message!");
    log::warn!("This is a warning!");
    log::error!("This is an error!");
}
```

### Advanced Configuration

```rust
use log::{info, debug, warn};
use grlog::{builder, Target};

fn main() {
    // Create a custom logger with specific settings
    let mut builder = builder();
    builder
        .filter_level(log::LevelFilter::Debug)
        .filter_module("hyper", log::LevelFilter::Info)
        .filter_module("my_crate::network", log::LevelFilter::Trace)
        .target(Target::Stdout)
        .buffer_size(2048);
    
    builder.init().unwrap();
    
    info!("This is an info message!");
    debug!("This is a debug message");
    warn!("This is a warning");
}
```

### Logging to a File

```rust
use log::info;
use grlog::{builder, Target};
use std::path::PathBuf;

fn main() {
    let mut log_path = PathBuf::from("/tmp");
    log_path.push("app.log");
    
    let mut builder = builder();
    builder
        .target(Target::File(log_path))
        .filter_level(log::LevelFilter::Info);
    
    builder.init().unwrap();
    
    info!("This will be written to the file!");
}
```

### Using Environment Variables

```rust
use grlog::init_from_env;

fn main() {
    // Initialize from RUST_LOG environment variable
    // Example: RUST_LOG=debug,cargo=info,my_module=trace cargo run
    init_from_env();
    
    log::info!("This is an info message!");
}
```

## Configuration Options

- **Targets**: Choose between stdout, stderr, or file output
- **Log Levels**: Trace, Debug, Info, Warn, Error, or Off
- **Module Filters**: Set different log levels for different modules
- **Buffer Size**: Configure the size of the async channel buffer

### Log Format

All log messages follow this format:
```
YYYY-MM-DD HH:MM:SS.mmm LEVEL [target] message
```

Example:
```
2023-05-14 10:30:45.123 INFO [my_app] Application started successfully
```

## Architecture

The core of `grlog` is built around:

1. **Gorust GMP Runtime**: Provides Go-like concurrency with goroutines
2. **Async Backend**: Uses channels for non-blocking message passing
3. **Log Writer Interface**: Pluggable writers for different output targets
4. **Formatter**: Standardized log message formatting with timestamps
5. **Builder Pattern**: Flexible configuration API similar to env_logger

The architecture ensures that even if the logging backend is temporarily slow, your application continues to run without blocking.

## Performance

By leveraging gorust's GMP (Goroutine, Monitor, Processor) model, `grlog` provides:

- Extremely lightweight goroutines for log processing
- Non-blocking message passing through channels
- Minimal overhead during log emission
- Efficient batching and buffering mechanisms
- Thread-safe concurrent logging from multiple application threads

## Comparison with Other Loggers

Unlike traditional Rust loggers that typically write synchronously to output streams, `grlog` uses an asynchronous approach that separates the act of requesting a log from the actual writing. This prevents I/O bottlenecks from affecting your application's performance.

## License

Licensed under MIT license ([LICENSE](LICENSE) or http://opensource.org/licenses/MIT)

## Contributing

We welcome contributions! Please feel free to submit a Pull Request. For bug reports or feature requests, open an issue on GitHub.

## Changelog

### v0.1.0
- Initial release
- Asynchronous logging using gorust GMP runtime
- Support for stdout, stderr and file output
- Module-specific log level filtering
- Environment variable configuration support
- Timestamped log entries with millisecond precision