# eventline
Structured journaling + logging for Rust, with scopes you can replay.
eventline records a complete, append-only execution history (events + scopes), while letting you control what gets emitted to console/files via log level and sink toggles.
---
## Features
- Append-only journal of structured records (events + scope exits)
- RAII scopes with duration tracking and success/failure/aborted outcomes
- Per-outcome exit messages for clean `done:` lines
- Emission gating (log level) that does NOT affect recording
- Console and file sinks (toggleable, configurable formatting)
- Automatic log rotation with configurable size limits and backup retention
- Run headers written as raw bytes at the start of each log session
---
## What is eventline?
eventline is a small, predictable journaling/logging crate built for real systems software.
Core rule:
> Always record the full structured history.
> Only gate emission (console/file output) with log levels and sink toggles.
This makes eventline ideal for post-mortems, debugging, and deterministic "what happened?" replay.
---
## Quick Start
Add it to your project:
[dependencies]
eventline = "0.8.0"
Initialize once early:
eventline::runtime::init().await;
Log events:
eventline::info!("starting");
eventline::debug!("debug details: {}", 123);
eventline::warn!("something looks off");
eventline::error!("something failed: {}", "oops");
Create a scope:
eventline::scope!("config", {
eventline::info!("loading config");
// work...
});
Scopes with exit messages:
eventline::scope!(
"config",
success="loaded",
failure="failed",
aborted="aborted",
{
// work...
});
This produces a final line like:
done: config#12 loaded [success] (3.2ms)
*(Exact formatting depends on runtime settings.)*
---
## Recording vs Emission (important)
- **Recording** always happens — the journal stores the full structured history.
- **Emission** is controlled by global log level and enabled sinks.
You get full fidelity history without spamming stdout.
---
## Runtime Configuration
Console output:
eventline::runtime::enable_console_output(true);
eventline::runtime::enable_console_color(true);
eventline::runtime::enable_console_timestamp(false);
eventline::runtime::enable_console_duration(true);
File output (append, no rotation):
eventline::runtime::enable_file_output("/tmp/app.log")?;
File output with automatic rotation:
use eventline::runtime::{LogPolicy, RunHeader};
eventline::runtime::enable_file_output_rotating(
"logs/app.log",
LogPolicy::default(), // 5 MiB max, 5 backups
Some(RunHeader::new("my-app")), // with PID annotation
)?;
Rotation renames the active log to `app.log.1`, shifts older backups up, and
opens a fresh `app.log`. The oldest backup beyond `keep_backups` is silently
dropped.
Disable all output (still records):
eventline::runtime::disable_all_output();
Set global log level (emission threshold only):
eventline::runtime::set_log_level(eventline::runtime::LogLevel::Debug);
---
## Log Rotation
`LogPolicy` controls when and how rotation happens:
use eventline::runtime::LogPolicy;
// Custom: 10 MiB max, keep 3 backups
let policy = LogPolicy::new(10 * 1024 * 1024, 3);
// Or use the defaults (5 MiB, 5 backups)
let policy = LogPolicy::default();
Rotation is triggered automatically before a record is written that would push
the file past `max_bytes`. Set `keep_backups` to `0` to simply delete the log
on rotation rather than keeping any history.
---
## Run Headers
A `RunHeader` is a single decorated line written as raw bytes at the start of a
log session, before structured records begin. It is always visible in the file
regardless of log level.
use eventline::runtime::RunHeader;
// With PID:
// ==================== my-daemon (pid=18432) ====================
RunHeader::new("my-daemon")
// Without PID:
// ====================== my-daemon ======================
RunHeader::without_pid("my-daemon")
// Custom width:
RunHeader::new("my-daemon").with_width(80)
When appending to an existing non-empty log file, a blank separator line is
inserted automatically before the header so run boundaries are clearly visible.
---
## Design Notes
- Records are append-only and never rewritten
- Scopes are created on enter and finalized exactly once on exit
- The journal is the canonical execution history
- Rendering and runtime only affect presentation, not data
- Rotation and headers operate on raw bytes and bypass the record pipeline intentionally
---
## Module Layout
- `core/` — data types only (Record, Scope, ids, Outcome, guards)
- `journal/` — append-only buffer, writers, rotation logic, structured fields
- `render/` — canonical formatting for console and file output
- `runtime/` — global config, sinks, filtering policy, run headers
- `macros` — `info!`, `debug!`, `warn!`, `error!`, `scope!`
---
## License
MIT