/// SDK — RUST
Rust SDK STABLE
Synchronous client on ureq, mirroring the Go SDK's surface.
Client is cheap to clone — all clones share the same queue
and worker thread. Covers the full API including admin and read-only SQL;
log and tracing integrations ship behind feature
flags. Tested with a tiny_http mock-server suite.
Install
Not on crates.io yet — depend on the crate by path:
[dependencies]
duckgraph = { path = "sdks/rust" }
# optional integrations:
duckgraph = { path = "sdks/rust", features = ["log", "tracing"] }
Quickstart
use duckgraph::{Client, Entry, Options, Query};
let client = Client::new("http://localhost:8080", Options {
api_key: Some("dgk_…".into()),
gzip: true,
..Default::default()
})?;
client.log("info", "myapp", "started")?; // buffered
client.enqueue(Entry::new("myapp", "now")
.level("info").attrs(serde_json::json!({"port": 8080})
.as_object().unwrap().clone()))?;
client.send(&[Entry::new("myapp", "direct")])?; // immediate
let rows = client.query(&Query {
min_level: Some("error".into()),
..Default::default()
})?;
client.close()?; // drains + joins the worker
Logging integrations
Two optional features adapt the client to the standard Rust logging
facades — the counterpart of the Go SDK's slog handler.
log feature — ClientLogger
Implements log::Log. Record metadata (target,
module, file, line) becomes entry
attrs; register once at startup:
let logger = duckgraph::ClientLogger::new(client.clone(), "myapp")
.host("web-1")
.level(log::LevelFilter::Info);
log::set_boxed_logger(Box::new(logger))?;
log::set_max_level(log::LevelFilter::Info);
log::warn!("disk usage at {}%", 87); // → buffered entry
tracing feature — DuckgraphLayer
Implements tracing_subscriber::Layer. Event fields become
attrs and the enclosing span name is attached:
use tracing_subscriber::prelude::*;
tracing_subscriber::registry()
.with(duckgraph::DuckgraphLayer::new(client.clone(), "myapp"))
.init();
tracing::info!(port = 8080, "listening"); // fields → attrs
Reference
Client lifecycle
| Method | Behaviour |
|---|---|
Client::new(base, Options) | Spawns the duckgraph-flusher worker thread. |
Client::connect(base) | Default options. |
Client::login(base, user, pass, Options) | Authenticates → holds the dgs_ token. |
close() / drop last clone | Drain queue, flush, join worker. |
Options
| Field | Default | Purpose |
|---|---|---|
api_key / token | — | dgk_ key or dgs_ session |
batch_size | 512 | Max entries per POST |
flush_interval | 2s | Buffer flush cadence |
queue_size | 8192 | Bounded channel capacity |
gzip | false | flate2 request compression |
retries | 3 | Attempts on 429/5xx/network errors |
timeout | 30s | Per-request (tail stream exempt) |
on_error | — | Arc<dyn Fn(Error)> async-failure callback |
agent | — | Custom ureq::Agent — proxies, TLS |
Read & admin surface
| Method | Endpoint |
|---|---|
query(&Query) / query_post | /v1/logs · /v1/query |
stats(window, bucket) | /v1/stats |
services() · metrics() · system() | /v1/services · /v1/metrics · /v1/system |
health() · me() · logout() | /healthz · /v1/auth/me · /v1/auth/logout |
tail(&Query) → Tail | /v1/logs/tail — SSE Iterator<Result<Row>> |
list_users · create_user · update_user · delete_user | /v1/users |
list_api_keys · create_api_key · revoke_api_key | /v1/apikeys |
sql(statement) → SqlResult | POST /v1/sql — admin, read-only |
Errors & status
Errorenum —Api(server 4xx/5xx),Http(transport),Json,Io,Dropped(queue full),Closed(client shut down).- Tests —
cargo testruns thetiny_httpmock-server suite: enqueue/flush, retries on 503, interval flush, tail, admin.cargo test --all-featuresadds the log/tracing integrations. - crates.io — PENDING publish pending; use a path dependency until then.
Source: sdks/rust/ — lib.rs re-exports
Client, Options, Tail, the
Error/Result types and all serde models.