oluso 0.2.0

AI-powered error monitoring for Rust applications: automatic panic reporting, breadcrumb tracking, and intelligent error grouping.
Documentation

oluso

AI-powered error monitoring for Rust applications: automatic panic reporting, breadcrumb tracking, and intelligent error grouping.

Installation

cargo add oluso

Requires an async runtime -- built on tokio and reqwest.

Usage

use oluso::{Client, Options};

#[tokio::main]
async fn main() {
    let client = Client::new(Options::new("your-api-key"));
    client.install_panic_hook();

    if let Err(err) = do_work().await {
        client.capture_error(&err).await;
    }
}

async fn do_work() -> Result<(), std::io::Error> {
    Ok(())
}

install_panic_hook reports any panic as a critical error (with a full backtrace, and without replacing Rust's normal "thread panicked at ..." stderr output) and needs no further wiring, as long as the panic happens with a Tokio runtime current -- see Panics below for the one case it can't cover.

Breadcrumbs & User Context

use oluso::{NewBreadcrumb, UserContext};

client.set_user_context(UserContext::new("user_456"));
client.add_breadcrumb(NewBreadcrumb::new("user started checkout").category("action"));

if let Err(err) = do_checkout().await {
    client.capture_error(&err).await;
}

Request-scoped context

A single process handles many concurrent requests, so a plain global breadcrumb list would mix up breadcrumbs from different requests. Wrap each unit of work (a request handler, typically) in [Client::run_in_scope] to isolate it:

client
    .run_in_scope(|| async {
        client.add_breadcrumb(NewBreadcrumb::new("request started"));
        handle_request().await
    })
    .await;

This is built on [tokio::task_local!], which -- unlike Node's AsyncLocalStorage -- only follows a single top-level task's .awaits. It does not propagate into a tokio::spawned task; re-enter the scope explicitly inside spawned work if it should still report against the same request.

Calling add_breadcrumb/set_user_context/set_custom_context outside run_in_scope (e.g. at startup) falls back to a single shared store rather than silently dropping the data -- fine for a one-off script, not meant for concurrent request handling.

Panics

install_panic_hook reports a panic by spawning onto whatever Tokio runtime is current at the moment it happens (tokio::runtime::Handle::try_current()), since panic hooks are synchronous but reporting needs an .await. That covers the overwhelmingly common case -- a panic inside a request handler on an async web framework -- but if a panic happens on a plain std::thread with no Tokio runtime around it, there's nothing to spawn the send onto, so it's logged to stderr only, not reported.

Manual Reporting

use oluso::Severity;

// A concrete error type: reports as its own type name (`std::io::Error`, etc).
client.capture_error(&err).await;

// A type-erased error (`Box<dyn Error>`, `anyhow::Error`, ...): the concrete
// type name is already gone by the time you have one of these, so supply it.
client.capture_dyn_error("PaymentError", err.as_ref()).await;

// Not tied to a Rust error value at all.
client.capture_message("disk usage above 90%", Severity::High).await;

Attaching a request

There's no framework-specific RequestContext builder in this crate -- construct one from whatever your framework hands you and attach it:

use oluso::RequestContext;

client
    .capture_error_with_request(
        &err,
        RequestContext {
            url: req.uri().to_string(),
            method: req.method().to_string(),
            headers: Some(headers_as_map(req.headers())),
            query: None,
            body: None,
        },
    )
    .await;

Advanced Configuration

use oluso::{Options, Severity};
use std::time::Duration;

let options = Options::new("your-api-key")
    .endpoint("https://your-self-hosted-instance.example.com/api/v1/error/report")
    .environment("staging")
    .default_severity(Severity::Medium)
    .max_breadcrumbs(50)
    .max_errors_per_minute(100)
    .timeout(Duration::from_secs(10))
    .sensitive_keys(vec!["ssn".to_string(), "internal_id".to_string()])
    .should_report(|message| !message.contains("expected"));

Monitor outcomes, heartbeats, and workflows

Create the matching monitor under Project → Monitors, then use the existing client:

use oluso::{AssertionOptions, HeartbeatOptions, MonitorReference, WorkflowEventOptions};
use serde_json::json;

client
    .heartbeat(
        &std::env::var("OLUSO_BACKUP_HEARTBEAT_URL")?,
        HeartbeatOptions { context: json!({"job": "nightly-backup", "rows": 12_402}), ..Default::default() },
    )
    .await?;

let mut assertion = AssertionOptions::new(MonitorReference::by_name("checkout-total"), charged == expected);
assertion.expected = json!(expected);
assertion.actual = json!(charged);
assertion.duration_ms = Some(duration.as_millis() as u64);
assertion.context = json!({"order_id": order_id});
client.assert_outcome(assertion).await?;

let mut deployment = client.workflow(MonitorReference::by_name("production-deployment"), None);
deployment.checkpoint("queued", WorkflowEventOptions { context: json!({"commit_sha": commit_sha}), ..Default::default() }).await?;
deployment.checkpoint("built", WorkflowEventOptions { context: json!({"artifact": artifact}), ..Default::default() }).await?;
deployment.checkpoint("deployed", WorkflowEventOptions { context: json!({"region": "lon1"}), ..Default::default() }).await?;
deployment.complete(None, WorkflowEventOptions { context: json!({"release": artifact}), ..Default::default() }).await?;

Use MonitorReference::by_id("...") for an immutable reference. The heartbeat URL is a monitor-specific secret shown once at creation. Evidence is recursively redacted and bounded; transient failures retry with exponential backoff, permanent 4xx responses do not, and the project connection string is never attached to a heartbeat request.

Error Report Structure

Reports sent to the API include:

  • Metadata: Title, message, stack trace (for panics), severity, tags.
  • Context: Request details when attached, server details (hostname, OS, arch, pid).
  • History: Breadcrumbs leading up to the error.
  • Identification: Fingerprint for deduplication and user ID.

License

MIT