<p align="center">
  <img height="300" src="https://codeberg.org/mo8it/logs-wheel/raw/branch/main/wheel.svg" />
</p>

<p align="center">Rolling log files with compression</p>

This library offers the struct [`LogFileInitializer`](https://docs.rs/logs-wheel/latest/logs_wheel/struct.LogFileInitializer.html) to get a log file inside a logs directory.
It uses a rolling strategy that works like the wheel image above 🎡

The initializer has the fields `directory`, `filename`, `max_n_old_files` and `preferred_max_file_size_mib`.

Rolling will be applied to the file `directory/file` if all the following conditions are true:

- The file already exists.
- The file has a size >= `preferred_max_file_size_mib` (in MiB).
- No rolling was already done today.

In the case of rolling, the file will be compressed with GZIP to `directory/filename-YYYYMMDD.gz` with today's date (in UTC).

If rolling was applied and the number of old files exceeds `max_n_old_files`, the oldest file will be deleted.

It is important to know that **rolling happens only on initialization**.
The [`init` method](https://docs.rs/logs-wheel/latest/logs_wheel/struct.LogFileInitializer.html#method.init) returns a normal `File`.
It will not apply rolling if your program runs for multiple days without being restarted.
This has the following advantages:

- No overhead on writing to check when to roll.
- No latency spikes during the actual rolling.
- The whole logs of one run (from start to termination) are inside one file.

Your program should restart anyway every couple of days when restart the host after a system update.
But if you really want rolling every fixed amount of days while your program is running,
you can use your own type that calls the [`init` method](https://docs.rs/logs-wheel/latest/logs_wheel/struct.LogFileInitializer.html#method.init) under the hood when rolling should happen and then swap the file.

For more details, read the documentation of the [`LogFileInitializer` struct](https://docs.rs/logs-wheel/latest/logs_wheel/struct.LogFileInitializer.html)
and its [`init` method](https://docs.rs/logs-wheel/latest/logs_wheel/struct.LogFileInitializer.html#method.init).

## Example

We will see what happens when calling the [`init` method](https://docs.rs/logs-wheel/latest/logs_wheel/struct.LogFileInitializer.html#method.init)
with the following field values for the initializer:

```rust
use logs_wheel::LogFileInitializer;

let log_file = LogFileInitializer {
  directory: "logs",
  filename: "test",
  max_n_old_files: 2,
  preferred_max_file_size_mib: 1,
}.init()?;

Ok::<(), std::io::Error>(())
```

This method call will always return the file `logs/test` at the end.
But we will discuss its side effects.

### First call

The first call will create the directory `logs/` in the current directory (because we specified a relative path) with the file `test` inside it.

Content of `logs/`:

- `test`

### Later call

If we call the same function again on the date 2023-11-12 (in UTC) and the size of the file `logs/test` is bigger than 1 MiB,
the file will be compressed to `logs/test-20231112.gz`.

The file `logs/test` will be returned after truncation (empty file).

Content of `logs/`:

- `test`
- `test-20231112.gz`

### Call on the same day

If we call the same function again on the same day, nothing will change,
even when the size of `logs/test` is bigger than 1 MiB.

The file `logs/test` will be open in append mode.

Content of `logs/`:

- `test`
- `test-20231112.gz`

### Call on a later day

If we call the same function again on the next day and the size of the file `logs/test` is bigger than 1 MiB,
the file will be compressed to `logs/test-20231113.gz`.

The file `logs/test` will be returned after truncation.

Content of `logs/`:

- `test`
- `test-20231113.gz`
- `test-20231112.gz`

### Call on a later day with an exceeded number of old files

Now, we already have 2 old files which means that we reached the limit `max_n_old_files`.
If we call the same function again on the next day and the size of the file `logs/test` is bigger than 1 MiB,
the file will be compressed to `logs/test-20231114.gz`.
The oldest file `test-20231112.gz` will be deleted.

The file `logs/test` will be returned after truncation.

Content of `logs/`:

- `test`
- `test-20231114.gz`
- `test-20231113.gz`

## Tracing Subscriber

You can use this library with the [tracing](https://docs.rs/tracing/latest/tracing/) ecosystem!

Here is an example of how to use the returned file as a [tracing subscriber](https://docs.rs/tracing-core/0.1.32/tracing_core/subscriber/trait.Subscriber.html):

```rust
use logs_wheel::LogFileInitializer;
use std::sync::Mutex;

let log_file = LogFileInitializer {
  directory: "logs",
  filename: "test",
  max_n_old_files: 2,
  preferred_max_file_size_mib: 1,
}.init()?;

let writer = Mutex::new(log_file);
let subscriber = tracing_subscriber::fmt()
  .with_writer(writer)
  // … (other `SubscriberBuilder` methods)
  .finish();
# Ok::<(), std::io::Error>(())
```

## Similar crates

- [tracing-appender](https://docs.rs/tracing-appender/latest/tracing_appender/index.html): Offers [RollingFileAppender](https://docs.rs/tracing-appender/0.2.2/tracing_appender/rolling/struct.RollingFileAppender.html) which rolls every fixed amount of time while the program is running. But it doesn't compress old log files and doesn't delete any. `logs-wheel` can be used as an alternative. It can also be used in combination with [NonBlocking](https://docs.rs/tracing-appender/0.2.2/tracing_appender/non_blocking/struct.NonBlocking.html) for non blocking writes.
- [rolling-file](https://docs.rs/rolling-file/latest/rolling_file/index.html): Provides rolling every fixed amount of time while the program is running. No compression. Has to rename every file during the rolling because they are numbered.