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

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:

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

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.