Documentation Index
Fetch the complete documentation index at: https://docs.monk.com/llms.txt
Use this file to discover all available pages before exploring further.
Configuration
The SDK ships with production-ready defaults. Every setting is optional and can be overridden via the builder.
Client Builder
use std::time::Duration;
use monk_sdk::{MonkClient, RetryConfig, BufferConfig, BackpressureStrategy};
let client = MonkClient::builder()
.base_url("https://events-api.monk.com")
.api_key("mk_live_abc123")
.timeout(Duration::from_secs(10))
.retry(RetryConfig { /* ... */ })
.buffer(BufferConfig { /* ... */ })
.on_flush_failure(|count, error| {
eprintln!("dropped {count} events: {error}");
})
.build()?;
use monk_sdk::{MonkClient, ClientConfig};
let config = ClientConfig {
base_url: "https://events-api.monk.com".into(),
api_key: "mk_live_abc123".into(),
..Default::default()
};
let client = MonkClient::from_config(config)?;
Retry Policy
Control how the SDK retries transient failures with exponential backoff and jitter:
use std::time::Duration;
use monk_sdk::RetryConfig;
let retry = RetryConfig {
base_delay: Duration::from_millis(200),
max_delay: Duration::from_secs(10),
max_retries: 3,
deadline: Some(Duration::from_secs(60)),
circuit_breaker_threshold: 5,
circuit_breaker_cooldown: Duration::from_secs(15),
};
| Setting | Default | Description |
|---|
base_delay | 100ms | Initial delay before the first retry |
max_delay | 30s | Upper bound on retry delay |
max_retries | 5 | Maximum number of retry attempts |
deadline | 120s | Total time budget for all retries |
circuit_breaker_threshold | 10 | Consecutive failures before opening the circuit |
circuit_breaker_cooldown | 30s | How long the circuit stays open before allowing a test request |
Circuit Breaker
The SDK includes a built-in circuit breaker that transitions through three states:
- Closed — requests flow normally, failures are counted
- Open — all requests immediately fail with
MonkError::CircuitOpen (avoids hammering a degraded server)
- HalfOpen — after the cooldown, one test request is allowed through. If it succeeds, the circuit closes; if it fails, the circuit reopens
Buffer Configuration
Tune the in-memory event buffer used by ingest_buffered:
use std::time::Duration;
use monk_sdk::{BufferConfig, BackpressureStrategy};
let buffer = BufferConfig {
capacity: 50_000,
max_batch_size: 5_000,
flush_interval: Duration::from_secs(1),
max_concurrent_flushes: 8,
backpressure: BackpressureStrategy::Block,
};
| Setting | Default | Description |
|---|
capacity | 10,000 | Maximum events held in the buffer |
max_batch_size | 10,000 | Maximum events per flush batch |
flush_interval | 500ms | Time between automatic flushes |
max_concurrent_flushes | 4 | Parallel HTTP flush workers |
backpressure | FailFast | Behavior when the buffer is full |
Backpressure Strategies
| Strategy | Behavior |
|---|
FailFast | Returns MonkError::BufferFull immediately when the buffer is at capacity. Caller must handle the error. |
Block | Suspends the caller until space is available. Producers naturally slow down to match the flush rate. |
FailFast is the default and is safe for most use cases. Switch to Block in high-throughput pipelines where you never want to lose an event and can tolerate backpressure on the producer.
Flush Failure Callback
Register a handler that fires whenever a batch flush fails after exhausting all retries:
let client = MonkClient::builder()
.base_url("https://events-api.monk.com")
.api_key("mk_live_abc123")
.on_flush_failure(|count, error| {
eprintln!("ALERT: dropped {count} events: {error}");
// push to dead-letter queue, increment metrics, page on-call, etc.
})
.build()?;
Defaults Reference
| Setting | Default |
|---|
| HTTP timeout | 30s |
| Retry base delay | 100ms |
| Retry max delay | 30s |
| Max retries | 5 |
| Retry deadline | 120s |
| Circuit breaker threshold | 10 failures |
| Circuit breaker cooldown | 30s |
| Buffer capacity | 10,000 |
| Max batch size | 10,000 |
| Flush interval | 500ms |
| Max concurrent flushes | 4 |
| Backpressure strategy | FailFast |
