Module logger 

Structured, asynchronous telemetry for the Kosh server.

This module provides the entire logging infrastructure used by the server at runtime. It is intentionally decoupled from the HTTP request path: the server emits log entries through an in-memory channel, and a dedicated background task handles all blocking I/O (disk writes, Unix socket broadcasts) independently.

Architecture

Route Handler / Middleware
        │
        │  crate::info!(Module::Api, "...")  ← zero-cost if logger is inactive
        │
        ▼
GLOBAL_LOGGER (OnceLock<Sender<Entry>>)
        │
        │  mpsc channel  (bounded, non-blocking try_send)
        │
        ▼
Service::run()  ← dedicated tokio task
    ├── writes bincode-serialized Entry to a rolling daily .bin file
    └── broadcasts the same bytes over a Unix Datagram Socket
            └── consumed by the Ratatui admin CLI (kosh-cli)

Enabling the logger

The logger is opt-in. Call Service::start on startup and store the returned sender in GLOBAL_LOGGER. If GLOBAL_LOGGER is never initialized, all macros (info!, warn!, error!, fatal!) become complete no-ops with zero overhead.

Emitting log entries

Use the crate-level macros exported from macro rather than constructing Entry values manually:

info!(Module::Api, "user {} logged in", user_id);
warn!(Module::Storage, "disk usage above 90%");
error!(Module::Database, "query failed: {}", e);

Structs

Entry

A single structured log event emitted by the server.

Service

The background logging service.

Enums

Level

The severity level of a log entry.

Module

The server subsystem that produced a log entry.

Statics

GLOBAL_LOGGER

The global channel sender used to submit log entries to the background logging service.

SOCKET_ADDR

The filesystem path of the Unix Datagram Socket used for real-time log broadcasting.

Traits

Loggable

Allows an error type to declare its own log severity and module routing.

Functions

format_date_time

Produces the filename for a daily log file given a Unix timestamp in milliseconds.

logging_enabled

Returns true if the logging service has been initialized and is currently active.

path