📜 Cirious Codex Logger

Structured Logging & Event Tracing for the Cirious Ecosystem

Robust, extensible, and performance-oriented observability primitives designed for modern Rust applications.

📖 Overview

Cirious Codex Logger is the observability foundation of the Cirious ecosystem.

Built with performance, flexibility, and maintainability in mind, it provides structured logging, event tracing, metadata enrichment, and configurable dispatch pipelines for applications ranging from command-line tools to large-scale services.

Rather than being a simple logger, Codex Logger acts as a centralized event processing layer capable of capturing, formatting, filtering, and routing runtime information with minimal overhead.

Core Principles

• ⚡ Performance First
• 🧩 Fully Modular Architecture
• 📊 Structured Event Processing
• 🎨 Rich Terminal Experience
• 🔍 Production-Ready Observability
• 🦀 Native Rust Ergonomics

✨ Features

Structured Logging

Powerful logging macros with compile-time ergonomics:

trace!();
debug!();
info!();
warn!();
error!();

📂 Examples

Explore practical examples in the examples/ directory.

Metadata Enrichment

Every event can carry contextual information such as:

• Timestamp
• Log level
• Module path
• Source file
• Line number
• Thread information

Flexible Dispatch System

Route events to multiple destinations:

• Standard Output
• Standard Error
• Rolling Files
• Custom Dispatchers

Async Processing

Background-thread dispatching for reduced runtime impact.

Advanced Formatting

Choose between:

• Human-readable terminal output
• Structured JSON logs
• Custom formatters

Intelligent Filtering

Filter events by:

• Log level
• Module path
• Custom rules

Architectural Overview

graph LR
    %% Configuração de Layout Horizontal
    direction LR

    %% Nós
    Macro[Log Macro] -->|1. Creates| Record[Record Struct]
    
    subgraph Processing [Centralized Processing]
        Record -->|2. Filter| Filter{Filter}
        Filter -->|Allowed| Format[3. Formatter]
        Filter -->|Blocked| Drop((Drop))
    end

    subgraph Dispatch [Dispatch Pipeline]
        Format -->|4. Payload| Dispatcher[Dispatcher Trait]
        Dispatcher -->|Stdout| Term[Terminal]
        Dispatcher -->|Rolling| File[File System]
        Dispatcher -->|Async| Back[Background Thread]
    end

    %% Estilização externa
    Format -.->|Uses Styling| Style(cirious_codex_term)

    %% Estilos simples para legibilidade
    style Processing fill:#f9f9f9,stroke:#333
    style Dispatch fill:#eef2f5,stroke:#333

🚀 Quick Start

Add the crate to your project:

[dependencies]
cirious_codex_logger = "0.2"

Initialize a dispatcher and start logging:

use cirious_codex_logger::{
    init,
    info,
    StdoutDispatcher,
    StyledTerminalFormatter,
};

fn main() {
    let formatter = StyledTerminalFormatter;

    let dispatcher =
        Box::new(StdoutDispatcher::new(formatter));

    init(dispatcher)
        .expect("Failed to initialize logger");

    info!("Cirious Codex Logger initialized.");
    info!("Status: {}, Users: {}", "Online", 128);
}

🚧 Development Roadmap

✅ v0.1.0 — Foundation

• Core logging macros
• Terminal formatter
• JSON formatter
• Stdout / Stderr dispatchers
• Initial Cirious Term integration

✅ v0.2.0 — Production Readiness

• Global logger registration
• Metadata enrichment
• Log filtering
• Async dispatching
• Rolling file support
• Improved formatter API

🔭 v0.3.0 — Observability & Diagnostics

• Structured Fields (tracing style)
• MultiDispatcher
• Runtime Filter Reloading
• Scoped Context
• Panic Capture

📜 License

Licensed under either of the following, at your option:

• MIT License
• Apache License 2.0

Minimalist by design. Consistent in execution.

Engineered by Cirious Studio