queuerious 0.1.1

Rust SDK for Queuerious job queue observability platform
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# queuerious

Rust SDK for the [Queuerious](https://queuerious.dev) 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

```toml
[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.

```toml
# 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.

```rust
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.

```rust
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`](https://crates.io/crates/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

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

at your option.