Skip to main content

​
Rust SDK

The Monk Rust SDK is a production-grade async client for the Monk Events API (events-api.monk.com). It handles retries, circuit breaking, client-side buffering, and graceful shutdown out of the box.
The SDK is available on crates.io and the source is on GitHub.
This SDK covers the Events API only — the high-throughput endpoint for event ingestion and usage queries. It does not wrap the Monk API at api.monk.com (customers, meters, pricing, plans, contracts, etc.). For those resources, use the REST API directly.

​
Features

  • Automatic retries with exponential backoff and full jitter
  • Circuit breaker to avoid hammering a degraded server
  • In-memory event buffer with background batch flushing
  • Parallel concurrent flushes (configurable worker pool)
  • Configurable backpressure (FailFast or Block)
  • Flush failure callbacks for alerting and dead-letter handling
  • Graceful shutdown that waits for in-flight flushes
  • Client-side validation (fail fast, save a round-trip)
  • Idempotency key management (auto-generated UUIDv4 when omitted)
  • Typed request/response models with serde
  • TLS via rustls (no OpenSSL dependency)

​
Installation

Add the SDK to your Cargo.toml: 
[dependencies]
monk-sdk = "0.1"
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
Or via the command line: 
cargo add monk-sdk

​
Quick Start

use monk_sdk::{MonkClient, Event};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = MonkClient::builder()
        .base_url("https://events-api.monk.com")
        .api_key("mk_live_abc123")
        .build()?;

    let resp = client.ingest(
        Event::builder()
            .customer_id("cust_123")
            .event_name("api_call")
            .property("tokens", 42)
            .build()?
    ).await?;

    println!("accepted: {}", resp.idempotency_key);
    Ok(())
}
The client is Clone and Arc-wrapped, so you can share it across threads and tasks cheaply.

​
Architecture

MonkClient (Clone, Arc-wrapped)
├── ClientInner
│   ├── reqwest::Client (connection pooling)
│   ├── base_url
│   └── RetryPolicy
│       └── CircuitBreaker (Closed → Open → HalfOpen)
└── BufferWorker (background tokio task)
    ├── mpsc channel (bounded, configurable capacity)
    ├── Semaphore-limited parallel flush pool
    ├── flush on interval OR batch size threshold
    ├── on_flush_failure callback
    └── graceful shutdown: drain + wait for in-flight

​
Next Steps

Ingesting Events

Send single, batch, or buffered events

Querying Data

List events and query aggregated usage

Configuration

Customize retries, buffering, and timeouts

Error Handling

Handle errors gracefully with typed variants