🚀 Cirious Codex Metrics

A unified telemetry and Prometheus exposition layer for robust Rust applications.

📖 Overview

Cirious Codex Metrics is a lightweight, high-performance Rust crate designed to standardize observability. By unifying tracing for structured logging and span execution with the metrics ecosystem for Prometheus exposition, it provides developers with a frictionless, drop-in path to production-grade telemetry.

Instead of configuring multiple overlapping libraries in every new project, cirious_codex_metrics offers a single initialization point to get your logs formatted and your Prometheus /metrics endpoint serving immediately.

📋 Quick Start

Add the following to your Cargo.toml:

[dependencies]
cirious_codex_metrics = "0.1.0"

Basic Usages

use cirious_codex_metrics::{metrics_registry::counter, tokio, LogFormat, TelemetryBuilder};
use std::net::SocketAddr;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
  let addr = SocketAddr::from(([127, 0, 0, 1], 9100));

  // Example A: Bootstrap using the Styled Terminal profile (Great for Dev environments)
  TelemetryBuilder::new()
    .with_prometheus_addr(addr)
    .with_format(LogFormat::Styled)
    .init()?;

  // Example B: Switch to standard JSON output if deploying to Staging/Prod
  // TelemetryBuilder::new()
  //     .with_prometheus_addr(addr)
  //     .with_format(LogFormat::Json)
  //     .init();

  loop {
    counter!("cirious_processed_ticks_total").increment(1);
    tokio::time::sleep(Duration::from_secs(1)).await;
  }
}

🚧 Current Status & Roadmap

✅ v0.1.0 — Initial Release (Completed)

• Ecosystem Logger Integration: Intercept lifecycle state using native codex_logger dispatchers, eliminating redundant external dependencies.
• Ecosystem Result Integration: Use cirious_codex_result for structured error handling and result types.
• Format Profile Support: Native compliance with JsonFormatter and StyledTerminalFormatter for environmental log layout switching.
• Prometheus Exporter Setup: Integrate metrics-exporter-prometheus to automatically manage registries and formatting.
• Standalone HTTP Endpoint: Spin up a lightweight, background HTTP listener dedicated to serving the /metrics scrape target.
• Ergonomic Facade Re-exports: Module isolation for metrics_registry and tokio to keep user dependencies clean.
• Documentation & Examples: Write comprehensive doc comments and provide runnable workspace integration examples.
• Publish: push cirious_codex_metrics to crates.io as a standalone crate.

🚀 v0.2.0 — Production Readiness & Integrations (Planned)

• Ecosystem Error Handling Integration: Transition from raw panic statements on HTTP socket binding failures to structured diagnostic returns leveraging cirious_codex_result::CodexError.
• HTTP Middleware (Tower/Axum): Deliver plug-and-play middleware configurations to systematically track server request rates, routing latencies, and error counters.
• Host System Metrics: Implement automated background loop scraping for runtime system parameters (CPU cycles, memory allocation, and OS threads).

📜 License

Licensed under either of the following, at your option:

• MIT License
• Apache License 2.0