Module logging 

Structured logging infrastructure with JSON output and OpenTelemetry integration.

This module provides logging functionality for Cadmus, including:

• JSON-structured logs written to rotating files
• Configurable log levels and filtering
• Automatic log file cleanup based on retention policies
• Optional OpenTelemetry export (when otel feature is enabled)
• Unique run ID for correlating logs across a session

Architecture

The logging system is built on the tracing crate ecosystem:

• tracing_subscriber for composable logging layers
• tracing_appender for non-blocking file I/O
• JSON formatting for structured, machine-readable logs
• EnvFilter for flexible log level control

Each application run generates a unique Run ID (UUID v7) that appears in:

• The log filename: cadmus-<run_id>.json
• OpenTelemetry resource attributes
• All log entries for correlation

Log File Management

Log files are automatically managed:

• Files are named with the run ID: cadmus-<run_id>.json
• Older files are deleted when max_files limit is exceeded
• Cleanup happens at initialization, keeping only the most recent files

Configuration

Logging is configured via LoggingSettings:

[logging]
enabled = true
level = "info"
max-files = 3
directory = "logs"
otlp-endpoint = "http://localhost:4318"  # Optional

The log level can be overridden with the RUST_LOG environment variable:

RUST_LOG=debug ./cadmus
RUST_LOG=cadmus::view=trace,info ./cadmus

Example Usage

use cadmus_core::settings::LoggingSettings;
use cadmus_core::logging::{init_logging, shutdown_logging, get_run_id};

let settings = LoggingSettings {
    enabled: true,
    level: "info".to_string(),
    max_files: 3,
    directory: "logs".into(),
    otlp_endpoint: None,
};

// Initialize at application startup
init_logging(&settings)?;
eprintln!("Started with run ID: {}", get_run_id());

// Use tracing macros throughout the application
tracing::info!("Application started");

// Shutdown at application exit (flushes buffers)
shutdown_logging();

Constants

GIT_VERSION 🔒

LOG_FILE_PREFIX 🔒

LOG_FILE_SUFFIX 🔒

Statics

LOG_GUARD 🔒

RUN_ID 🔒

Functions

build_filter 🔒

Builds an EnvFilter from settings or environment variables.

cleanup_run_logs 🔒

Removes old log files to maintain the configured retention limit.

collect_run_log_entries 🔒

Collects all Cadmus log file entries from the specified directory.

get_run_id

Returns the unique run ID for this application session.

init_logging

Initializes the logging system with JSON output and optional OpenTelemetry export.

is_run_log_entry 🔒

Determines whether a directory entry is a Cadmus log file.

shutdown_logging

Gracefully shuts down the logging system and flushes buffered data.