Crate timber_rust 

🌲 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.

Available loggers

• Silent: logger::Silent (the messages are dropped)
• Direct (sync logging): logger::Direct (uses services)
• Queued (async logging): logger::Queued (uses services)
• Loki (batched HTTPS): logger::Loki (requires feature loki)
• CloudWatch (batched HTTPS): logger::CloudWatch (requires feature aws)

Available services

• Loki (HTTPS): service::Loki (requires feature loki)
• ClousWatch (SDK): service::CloudWatch (requires feature aws)
• ClousWatch (STDOUT): service::CloudWatchCout (requires feature awscout)
• Io services: service::IoWrite
  • File: service::StandardFileWrite
  • Buffered file: service::StandardBufferedFileWrite
  • Boxed writers: service::StandardBoxedIoWrite
• Fmt services: service::FmtWrite
  • String: service::StandardStringFmtWrite
  • Boxed writers: service::StandardBoxedFmtWrite
• Conceptual:
  • Vector: 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:

[dependencies]
timber-rust = { git = "[https://github.com/dante19031999/timber-rust](https://github.com/dante19031999/timber-rust)" }

🚀 How to get started

Logging into stdout/stderr

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

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!"));

• See: service::StandardFileWrite

Logging into loki

use timber_rust::service::LokiConfig;
use timber_rust::LoggerFactory;
use timber_rust::LogLevel;

let mut config = LokiConfig::new("localhost::3001");

// An async batched loki logger
let logger = LoggerFactory::loki().config(config).build();

// Log something
logger.log(("INFO", "Hello world!"));
logger.log((LogLevel::Info, "Hello world!"));

• See: LokiLogger
• See: 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. You may build your own implementing the trait Service.
• LokiLogger: An specific batched logger to loki. Can be customized using a custom LokiService.
• Don’t forget to check first our inbuilt LoggerFactory!
• You may directly implement LoggerImpl if you wish to bypass the 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 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.

Re-exports

pub use factory::LoggerFactory;

pub use service::Fallback;

pub use service::Service;

pub use logger::CloudWatch as CloudWatchLogger;

pub use logger::Direct as DirectLogger;

pub use logger::Level as LogLevel;

pub use logger::Logger;

pub use logger::LoggerImpl;

pub use logger::Loki as LokiLogger;

pub use logger::Queued as QueuedLogger;

pub use logger::Silent as SilentLogger;

pub use logger::Status as LoggerStatus;

Modules

factory

logger

service

Structs

BasicAuth

Credentials for HTTP Basic Authentication.

Config

ErrorMessageImpl

A message containing a boxed Error object.

JsonMessageImpl

A message implementation that stores structured JSON data.

LogManager

LogManager acts as a registry and dispatcher for multiple logging channels.

Message

The public-facing container for any log message.

MessageFactory

The primary entry point for creating log messages.

StringMessageImpl

A standard text-based log message.

Enums

Concurrency

Defines the execution strategy for log processing and delivery.

Entry

Represents the destination and configuration for a logging channel.

EntryConfig

Represents the destination and configuration for a logging channel.

FlexibleDuration

Timestamp

Traits

MessageImpl

A trait for Message implementations that can be formatted and downcast.