beatwise 0.2.0

A lightweight heartbeat-based task liveness monitor with fixed and learned timing
Documentation
  • Coverage
  • 41.67%
    65 out of 156 items documented1 out of 1 items with examples
  • Size
  • Source code size: 123.0 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 2.4 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 4s Average build duration of successful builds.
  • all releases: 3s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • Gardlok/beatwise
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • Gardlok

Beatwise

Beatwise is a small Rust library for watching long-running work.

A task calls beat() whenever it makes progress. Beatwise tracks that rhythm and reports whether the task is Starting, Learning, Healthy, Late, or Stopped.

It works well for background workers, sync loops, schedulers, queue consumers, device pollers, backups, peer maintenance, and other jobs that should keep moving.

Beatwise can watch a known interval, learn a task's normal pace, or learn a repeating cycle. It uses only the standard library, starts no threads, and does not require an async runtime.

What it provides

  • Fixed deadlines for predictable work.
  • Learned timing for jobs whose pace changes.
  • A robust model for occasional outliers.
  • Repeating-pattern detection for multi-phase work.
  • Independent transition cursors and aggregate health reports.
  • Bounded memory with no event queue or unbounded history.

All timing stays inside the caller's process. Fixed heartbeats use atomics and a monotonic clock read. Learned tasks add one small mutex. Stopped tasks remain visible until explicitly purged.

Learn a task's normal pace

EWMA is the default learned model. It uses constant memory and adapts gradually as the task changes:

use std::time::Duration;
use beatwise::{Adaptation, LearnedTiming, Monitor, TaskConfig, Timing};

let monitor = Monitor::new();
let timing = LearnedTiming::default()
    .with_minimum_samples(8)
    .with_minimum_grace(Duration::from_millis(25))
    .with_sensitivity(4.0)
    .with_adaptation(Adaptation::Slow);

let heartbeat = monitor.register(TaskConfig::new(
    "database-sync",
    Timing::Learned(timing),
))?;

heartbeat.beat()?;

for status in monitor.snapshot() {
    println!("{}: {:?}", status.name, status.timing);
}

# Ok::<(), Box<dyn std::error::Error>>(())

For jobs with occasional long pauses or extreme outliers, use the bounded robust window:

use std::time::Duration;
use beatwise::{Adaptation, LearnedTiming, LearningModel, Monitor, TaskConfig, Timing};

let monitor = Monitor::new();
let timing = LearnedTiming::default()
    .with_minimum_samples(9)
    .with_minimum_grace(Duration::from_millis(25))
    .with_adaptation(Adaptation::Slow)
    .with_model(LearningModel::robust_window(9));
let heartbeat = monitor.register(TaskConfig::new(
    "bursty-worker",
    Timing::Learned(timing),
))?;

let task_id = heartbeat.id();
monitor.retrain(task_id)?;

# Ok::<(), Box<dyn std::error::Error>>(())

Robust windows use odd capacities from 5 through 31. Monitor::retrain clears the learned baseline without replacing the task ID or heartbeat handle.

Learn repeating work

Some healthy jobs alternate between short and long phases. The repeating-pattern model learns that cycle instead of forcing it into one average:

use std::time::Duration;
use beatwise::{
    Adaptation, LearnedTiming, LearningModel, Monitor, PatternConfig, TaskConfig, Timing,
};

let monitor = Monitor::new();
let pattern = PatternConfig::new(6, 3)
    .with_tolerance_percent(10)
    .with_minimum_contrast_percent(20);
let timing = LearnedTiming::default()
    .with_minimum_samples(9)
    .with_startup_grace(Duration::from_secs(30))
    .with_minimum_grace(Duration::from_millis(25))
    .with_sensitivity(4.0)
    .with_adaptation(Adaptation::Slow)
    .with_model(LearningModel::RepeatingPattern(pattern));
let heartbeat = monitor.register(TaskConfig::new(
    "phased-worker",
    Timing::Learned(timing),
))?;

heartbeat.beat()?;

# Ok::<(), Box<dyn std::error::Error>>(())

Patterns can have two through eight phases and require three through eight cycles. Beatwise learns from at most 64 intervals. An outlier still counts as a heartbeat and advances the phase, but it does not replace the trusted baseline.

Watch state changes

A transition cursor reports meaningful state changes without callbacks or a shared event queue:

use std::time::Duration;
use beatwise::{HealthState, Monitor, TaskConfig, Timing};

let monitor = Monitor::new();
let heartbeat = monitor.register(TaskConfig::new(
    "worker",
    Timing::fixed(Duration::from_secs(1)),
))?;
let mut transitions = monitor.transition_cursor();

for transition in transitions.poll() {
    assert_eq!(transition.previous, None);
    assert_eq!(transition.current, HealthState::Starting);
}

heartbeat.beat()?;

for transition in transitions.poll() {
    println!(
        "{}: {:?} -> {:?}",
        transition.status.name,
        transition.previous,
        transition.current,
    );
}

# Ok::<(), Box<dyn std::error::Error>>(())

Each cursor is independent. poll() returns only state changes, ordered by task ID. Beatwise does not run callbacks or own an executor.

Build health endpoints

Use a summary for a lightweight health check or a full report when you need task details:

use std::time::Duration;
use beatwise::{HealthPolicy, HealthVerdict, Monitor, TaskConfig, Timing};

let monitor = Monitor::new();
let heartbeat = monitor.register(TaskConfig::new(
    "api-worker",
    Timing::fixed(Duration::from_secs(1)),
))?;

let readiness = monitor.summary(HealthPolicy::readiness());
assert_eq!(readiness.verdict, HealthVerdict::Degraded);
assert_eq!(readiness.counts.starting, 1);

heartbeat.beat()?;

let liveness = monitor.report(HealthPolicy::liveness());
println!(
    "verdict={:?}, considered={}, ignored={}",
    liveness.summary.verdict,
    liveness.summary.considered_tasks,
    liveness.summary.ignored_tasks,
);
for task in liveness.tasks.iter() {
    println!("{}: {:?}", task.name, task.health);
}

# Ok::<(), Box<dyn std::error::Error>>(())

readiness() treats starting and learning tasks as degraded. liveness() allows those states, fails late tasks, and ignores stopped records. strict() accepts only healthy tasks. Custom policies can change how any state affects the verdict.

Version note

Beatwise 0.2.0 replaces the old Thumper 0.1.x DJ, deck, and output API. The old implementation remains available in Git history.

Validation

From the repository root:

cargo fmt --all --check
cargo clippy --all-targets -- -D warnings
cargo test
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
cargo package --list
cargo package