queuerious 0.1.22

Rust SDK for Queuerious job queue observability platform
Documentation

queuerious

Rust SDK for the Queuerious job queue observability platform.

Report job lifecycle events (started, completed, failed, retrying, dead-lettered) from your Rust applications to Queuerious for real-time monitoring, alerting, and debugging.

Installation

[dependencies]
queuerious = "0.1"

Feature flags

Feature Description
tower Tower middleware for automatic job tracking
metrics Queue metrics collection traits + agent for pushing metrics to Queuerious
commands Remote command execution traits + agent for polling commands from Queuerious
agent Convenience — enables both metrics and commands

Features can be combined freely. Enabling metrics or commands (or both) gives you access to the Agent struct, which runs a background loop that registers with the Queuerious API, sends heartbeats, and handles whichever capabilities you've enabled.

# Metrics only — agent pushes queue metrics, no remote commands
queuerious = { version = "0.1", features = ["metrics"] }

# Commands only — agent polls and executes remote commands, no metrics
queuerious = { version = "0.1", features = ["commands"] }

# Both — full agent experience
queuerious = { version = "0.1", features = ["agent"] }

Quick start

Event reporting (no features required)

The core SDK reports job lifecycle events via batched HTTP calls. No agent or feature flags needed.

use queuerious::{QueuriousClient, JobEvent, Backend};

#[tokio::main]
async fn main() -> Result<(), queuerious::QueuriousError> {
    let client = QueuriousClient::builder()
        .api_key("qk_your_api_key")
        .endpoint("https://api.queuerious.dev")
        .build()?;

    // Report a job started event (non-blocking, batched)
    client.report(
        JobEvent::started("email-queue", Backend::RabbitMQ, "job-123", "SendEmail")
            .payload(serde_json::json!({"to": "user@example.com"}))
            .build()
    )?;

    // Gracefully shut down (flushes pending events)
    client.shutdown().await?;
    Ok(())
}

Agent (requires metrics and/or commands)

The agent is a long-running background task that registers with the Queuerious API, sends periodic heartbeats, and — depending on which features are enabled — collects and pushes queue metrics, polls for remote commands, or both.

use queuerious::{Agent, AgentConfig};
use std::sync::Arc;

// Build an agent using the client's connection details.
// Attach a MetricsCollector, a CommandExecutor, or both,
// depending on which features you've enabled.
let agent = Agent::builder("qk_your_api_key", "https://api.queuerious.dev")
    .config(AgentConfig::new())
    // .metrics_collector(my_collector)   // when "metrics" is enabled
    // .command_executor(my_executor)     // when "commands" is enabled
    .build()?;

let (handle, shutdown_tx) = agent.spawn();

// ... later, trigger graceful shutdown:
let _ = shutdown_tx.send(());
handle.await.ok();

The MetricsCollector and CommandExecutor traits are designed for queue backend adapters to implement. See the adapter crate section below for ready-made implementations.

Queue backend adapters

For automatic lifecycle tracking with specific queue backends, use one of the adapter crates:

Crate Backend Description
queuerious-lapin RabbitMQ Wraps lapin::Consumer with automatic event tracking, metrics collection, and command execution

Adapter crates provide TrackedConsumer for lifecycle events, plus implementations of MetricsCollector and CommandExecutor that you can plug directly into the agent — or use the ObservabilityRuntime to wire everything together in one call.

License

Licensed under either of

at your option.