Skip to content

Commit

Permalink
Refactor documentation and examples
Browse files Browse the repository at this point in the history
  • Loading branch information
SpriteOvO committed Jul 4, 2024
1 parent 62de1c6 commit cdef50b
Show file tree
Hide file tree
Showing 42 changed files with 966 additions and 963 deletions.
45 changes: 21 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,25 @@
[![](https://img.shields.io/badge/docs.rs-spdlog--rs-ff69b4?style=flat-square&logo=rust)](https://docs.rs/spdlog-rs)
[![](https://img.shields.io/github/actions/workflow/status/SpriteOvO/spdlog-rs/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white)](https://github.com/SpriteOvO/spdlog-rs/actions/workflows/ci.yml)

A fast and combinable Rust logging crate, inspired by the C++ logging library [spdlog].
Fast, highly configurable Rust logging crate, inspired by the C++ logging library [spdlog].

## Features

- Very fast (see [Benchmarks]).
- Various log targets:
- Standard streams with optional colors.
- Files.
- Rotating log files by file size.
- Rotating log files hourly.
- Rotating log files daily.
- ... (more targets are implementing, PRs are welcome)
- Extendable with custom log targets.
- Compatible with [log crate] (optional).
- Asynchronous support.
- Configured via environment variable.
- Custom formatting.
- Log filtering - log levels can be modified in runtime as well as in compile time.
- Compatible with `log` crate.
- Custom log formats:
- compile-time zero-cost pattern or runtime pattern;
- manually implementing for more flexibility.
- Various combinable sinks:
- standard streams with optional color support;
- files (single file, rotating hourly, daily or by file size);
- platform-specific (e.g. `journald` for Linux and `OutputDebugStringW` for Windows);
- ... and able to implement one yourself.
- Configuring via environment variables or TOML[^1].
- More readable level filters.

[^1]: TOML deserialization support is working in progress, tracking issue [#25]

## Getting started

Expand All @@ -32,11 +33,11 @@ Add this to `Cargo.toml`:
spdlog-rs = "0.3"
```

The documentation of this crate is hosted on [docs.rs], and you can find examples under [./examples] directory.
The documentation of this crate is hosted on [docs.rs], and you can learn examples under [./examples] directory along with it.

If you have any questions or need help while using this crate, feel free to [open a discussion]. For feature requests or bug reports, please [open an issue].
If you have any trouble while using this crate, please don't hesitate to [open a discussion] for help. For feature requests or bug reports, please [open an issue].

## Supported Rust Versions
## Supported Rust versions

<!--
When updating this, also update:
Expand All @@ -55,22 +56,18 @@ The current minimum supported Rust version is 1.56.

Licensed under either of

* Apache License, Version 2.0
([LICENSE-APACHE](/LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license
([LICENSE-MIT](/LICENSE-MIT) or http://opensource.org/licenses/MIT)
* Apache License, Version 2.0 ([LICENSE-APACHE](/LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](/LICENSE-MIT) or http://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.
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.

[spdlog]: https://github.com/gabime/spdlog
[Benchmarks]: https://github.com/SpriteOvO/spdlog-rs/blob/main/spdlog/benches/README.md
[log crate]: https://crates.io/crates/log
[#25]: https://github.com/SpriteOvO/spdlog-rs/issues/25
[./examples]: https://github.com/SpriteOvO/spdlog-rs/tree/main/spdlog/examples
[docs.rs]: https://docs.rs/spdlog-rs/
[open a discussion]: https://github.com/SpriteOvO/spdlog-rs/discussions/new
Expand Down
4 changes: 2 additions & 2 deletions spdlog/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -147,8 +147,8 @@ name = "ftlog_3_level_off"
path = "benches/ftlog/3_level_off.rs"

[[example]]
name = "06_compatible_with_log_crate"
name = "06_log_crate"
required-features = ["log"]
[[example]]
name = "07_async_pool_sink"
name = "07_async"
required-features = ["multi-thread"]
38 changes: 0 additions & 38 deletions spdlog/examples/01_default_logger.rs

This file was deleted.

20 changes: 20 additions & 0 deletions spdlog/examples/01_macro.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
// All log macros and common types are under `spdlog::prelude` module.
use spdlog::prelude::*;

fn main() {
// Writes a log at "info" level with the info level, and this log will be
// processed by the global default logger - It will be output to `stdout`.
info!("program started");

let file = "config.json";

// They will be output to `stderr`.
error!("failed to open file: {}", file);
warn!("undetermined locale, defaults to `en_US.UTF-8`");

// Level "trace" and "debug" will be ignored by default, you can modify the
// level filter of the global default logger to enable all levels.
spdlog::default_logger().set_level_filter(LevelFilter::All);

trace!("position x: {}, y: {}", 11.4, -5.14);
}
59 changes: 0 additions & 59 deletions spdlog/examples/02_building_logger.rs

This file was deleted.

42 changes: 42 additions & 0 deletions spdlog/examples/02_file.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
use std::{env, sync::Arc};

use spdlog::{
prelude::*,
sink::{FileSink, RotatingFileSink, RotationPolicy},
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
configure_file_logger()?;
configure_rotating_file_logger()?;

Ok(())
}

fn configure_file_logger() -> Result<(), Box<dyn std::error::Error>> {
let path = env::current_exe()?.with_file_name("file.log");

let file_sink = Arc::new(FileSink::builder().path(path).build()?);
let new_logger = Arc::new(Logger::builder().sink(file_sink).build()?);
spdlog::set_default_logger(new_logger);

info!("this log will be written to the file `all.log`");

Ok(())
}

fn configure_rotating_file_logger() -> Result<(), Box<dyn std::error::Error>> {
let path = env::current_exe()?.with_file_name("rotating.log");

let file_sink = Arc::new(
RotatingFileSink::builder()
.base_path(path)
.rotation_policy(RotationPolicy::Daily { hour: 0, minute: 0 })
.build()?,
);
let new_logger = Arc::new(Logger::builder().sink(file_sink).build()?);
spdlog::set_default_logger(new_logger);

info!("this log will be written to the file `rotating.log`, and the file will be rotated daily at 00:00");

Ok(())
}
45 changes: 0 additions & 45 deletions spdlog/examples/03_file_sink.rs

This file was deleted.

60 changes: 60 additions & 0 deletions spdlog/examples/03_logger.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
use std::{env, sync::Arc, time::Duration};

use spdlog::{
prelude::*,
sink::{FileSink, Sink},
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
// `spdlog-rs` has a global default logger and logs will be processed by it
// by default, You can configure it.
let default_logger = spdlog::default_logger();
default_logger.set_level_filter(LevelFilter::All);

// Or completely replace it with a new one.
let path = env::current_exe()?.with_file_name("all.log");
let file_sink = Arc::new(FileSink::builder().path(path).build()?);

let new_logger = Arc::new(
Logger::builder()
.level_filter(LevelFilter::All)
.flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
.sink(file_sink.clone())
.build()?,
);
new_logger.set_flush_period(Some(Duration::from_secs(3)));
spdlog::set_default_logger(new_logger);

info!("this log will be written to the file `all.log`");

// In addition to having the global default logger, more loggers are allowed to
// be configured, stored and used independently.
let db = AppDatabase::new(file_sink)?;
db.write_i32(114514);

Ok(())
}

struct AppDatabase {
logger: Logger,
}

impl AppDatabase {
fn new(all_log_sink: Arc<dyn Sink>) -> Result<Self, Box<dyn std::error::Error>> {
let path = env::current_exe()?.with_file_name("db.log");
let db_file_sink = Arc::new(FileSink::builder().path(path).build()?);

let logger = Logger::builder()
.name("database")
.level_filter(LevelFilter::All)
.flush_level_filter(LevelFilter::MoreSevereEqual(Level::Warn))
.sinks([all_log_sink, db_file_sink])
.build()?;
Ok(Self { logger })
}

fn write_i32(&self, value: i32) {
// This log will be written to both files `all.log` and `db.log`.
trace!(logger: self.logger, "writing value {} to the database", value);
}
}
Loading

0 comments on commit cdef50b

Please sign in to comment.