Skip to main content

​
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()?;
You can also build from a config struct: 
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),
};
SettingDefaultDescription
base_delay100msInitial delay before the first retry
max_delay30sUpper bound on retry delay
max_retries5Maximum number of retry attempts
deadline120sTotal time budget for all retries
circuit_breaker_threshold10Consecutive failures before opening the circuit
circuit_breaker_cooldown30sHow 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:
  1. Closed — requests flow normally, failures are counted
  2. Open — all requests immediately fail with MonkError::CircuitOpen (avoids hammering a degraded server)
  3. 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,
};
SettingDefaultDescription
capacity10,000Maximum events held in the buffer
max_batch_size10,000Maximum events per flush batch
flush_interval500msTime between automatic flushes
max_concurrent_flushes4Parallel HTTP flush workers
backpressureFailFastBehavior when the buffer is full

​
Backpressure Strategies

StrategyBehavior
FailFastReturns MonkError::BufferFull immediately when the buffer is at capacity. Caller must handle the error.
BlockSuspends 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()?;
This is your last line of defense for events that could not be delivered. Use it to route failed events to a dead-letter queue or trigger an alert.

​
Defaults Reference

SettingDefault
HTTP timeout30s
Retry base delay100ms
Retry max delay30s
Max retries5
Retry deadline120s
Circuit breaker threshold10 failures
Circuit breaker cooldown30s
Buffer capacity10,000
Max batch size10,000
Flush interval500ms
Max concurrent flushes4
Backpressure strategyFailFast