[](https://github.com/dante19031999/timber-rust)
[](https://dante19031999.github.io/timber-rust/timber_rust/index.html)
[](https://dante19031999.github.io/timber-rust/about/licenses.html)
# 🌲 Timber Rust
## 🚀 Overview
**Timber Rust** is designed to provide a seamless integration for system logs and telemetry. It focuses on performance
and type-safety, allowing developers to switch between different observability backends with minimal configuration.
## ✨ Key Features
- **Blazing Fast:** Zero-cost abstractions following the Rust philosophy.
- **Pluggable Backends:** Support for multiple services (e.g., Loki) via feature flags.
- **Secure by Default:** Automatic vulnerability scanning and license compliance.
- **Docs-First:** Comprehensive API documentation integrated with [GitHub Pages](https://dante19031999.github.io/timber-rust/timber_rust/index.html).
### Available loggers
- Silent: [`logger::Silent`][crate::logger::Silent] (the messages are dropped)
- Direct (sync logging): [`logger::Direct`][crate::logger::Direct] (uses services)
- Queued (async logging): [`logger::Queued`][crate::logger::Queued] (uses services)
- Loki (batched HTTPS): [`logger::Loki`][crate::logger::Loki] (requires feature `loki`)
- CloudWatch (batched HTTPS): [`logger::CloudWatch`][crate::logger::CloudWatch] (requires feature `aws`)
### Available services
- Loki (HTTPS): [`service::Loki`][crate::service::Loki] (requires feature `loki`)
- ClousWatch (SDK): [`service::CloudWatch`][crate::service::CloudWatch] (requires feature `aws`)
- ClousWatch (STDOUT): [`service::CloudWatchCout`][crate::service::CloudWatchCout] (requires feature `awscout`)
- Io services: [`service::IoWrite`][crate::service::IoWrite]
- File: [`service::StandardFileWrite`][crate::service::StandardFileWrite]
- Buffered file: [`service::StandardBufferedFileWrite`][crate::service::StandardBufferedFileWrite]
- Boxed writers: [`service::StandardBoxedIoWrite`][crate::service::StandardBoxedIoWrite]
- Fmt services: [`service::FmtWrite`][crate::service::FmtWrite]
- String: [`service::StandardStringFmtWrite`][crate::service::StandardStringFmtWrite]
- Boxed writers: [`service::StandardBoxedFmtWrite`][crate::service::StandardBoxedFmtWrite]
- Conceptual:
- Vector: [`service::Vector`][crate::service::Vector]
## 📖 Documentation
Full technical documentation, including API references and module usage, is available at our GitHub Pages site.
## 📦 Installation
Add this to your `Cargo.toml`:
```toml
[dependencies]
timber-rust = { git = "[https://github.com/dante19031999/timber-rust](https://github.com/dante19031999/timber-rust)" }
```
## 🚀 How to get started
### Logging into stdout/stderr
```rust
use timber_rust::LoggerFactory;
use timber_rust::LogLevel;
use timber_rust::Concurrency;
// An async logger over stdout/stderr (1 worker)
let logger_stdout = LoggerFactory::cout().build(Concurrency::Async);
let logger_stderr = LoggerFactory::cerr().build(Concurrency::Sync);
// Log something
logger_stdout.log(("INFO", "Hello world!"));
logger_stderr.log((LogLevel::Info, "Hello world!"));
```
- See: [`service::StandardCoutWrite`]
- See: [`service::StandardCerrWrite`]
### Logging into a file
```rust
use timber_rust::LoggerFactory;
use timber_rust::LogLevel;
use timber_rust::Concurrency;
use std::fs::OpenOptions;
let mut file = OpenOptions::new()
.write(true) // Write
.append(true) // Append (not squash previous logs)
.create(true) // Create if not exits
.open("logs.txt").expect("Could not open file!");
// An async logger over a file (1 worker)
let logger = LoggerFactory::io().file(file).build(Concurrency::Async);
// Log something
logger.log(("INFO", "Hello world!"));
logger.log((LogLevel::Info, "Hello world!"));
# let _ = std::fs::remove_file("logs.txt");
```
- See: [`service::StandardFileWrite`]
### Logging into loki
```rust
# #[cfg(feature = "loki")]
use timber_rust::service::LokiConfig;
# #[cfg(feature = "loki")]
use timber_rust::LoggerFactory;
# #[cfg(feature = "loki")]
use timber_rust::LogLevel;
# #[cfg(feature = "loki")]
let mut config = LokiConfig::new("localhost::3001");
// An async batched loki logger
# #[cfg(feature = "loki")]
let logger = LoggerFactory::loki().config(config).build();
// Log something
# #[cfg(feature = "loki")]
logger.log(("INFO", "Hello world!"));
# #[cfg(feature = "loki")]
logger.log((LogLevel::Info, "Hello world!"));
```
- See: [`LokiLogger`]
- See: [`LokiConfig`][`service::LokiConfig`]
### Creating your own custom loggers
The library uses two main logger models:
- [`DirectLogger`]: A sync logger. Blocks until the process is finished.
- [`QueuedLogger`]: An async logger. Uses a crossbeam internal queue to dispatch logs.
- Both options use a [`Service`] as a backend. You may check or inbuilt [services][`service`]. You may build your own implementing the trait [`Service`][`crate::Service`].
- [`LokiLogger`]: An specific batched logger to loki. Can be customized using a custom [`LokiService`][`crate::service::Loki`].
- Don't forget to check first our inbuilt [`LoggerFactory`]!
- You may directly implement [`LoggerImpl`] if you wish to bypass the [service][`service`] system.
### Mutltichanel logging
Our logging system supports multichannel logging through [`LogManager`].
It is possible to create presets through [`Config`]. Though it is limited to what can be deduced at runtime.
Our [`Config`][`crate::Config`] implements [`serde::Serialize`] and [`serde::Deserialize`] for total freedom in congiguration storage.
The examples where built using JSON (the most common), but [`serde`] allows for any model.
## ⚖️ Credits & Licensing
This project relies on several open-source crates. You can find the full list of dependencies and their respective
licenses in our [Credits Report](https://dante19031999.github.io/timber-rust/about/licenses.html).