DUCKGRAPH® LOG INGESTION UNIT
SYS.OK REV 1.0

/// 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:

TOMLCARGO.TOML
[dependencies]
duckgraph = { path = "sdks/rust" }
# optional integrations:
duckgraph = { path = "sdks/rust", features = ["log", "tracing"] }

Quickstart

RUSTUSAGE
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:

RUSTLOG FACADE
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:

RUSTTRACING LAYER
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

MethodBehaviour
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 cloneDrain queue, flush, join worker.

Options

FieldDefaultPurpose
api_key / token—dgk_ key or dgs_ session
batch_size512Max entries per POST
flush_interval2sBuffer flush cadence
queue_size8192Bounded channel capacity
gzipfalseflate2 request compression
retries3Attempts on 429/5xx/network errors
timeout30sPer-request (tail stream exempt)
on_error—Arc<dyn Fn(Error)> async-failure callback
agent—Custom ureq::Agent — proxies, TLS

Read & admin surface

MethodEndpoint
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) → SqlResultPOST /v1/sql — admin, read-only

Errors & status

  • Error enum — Api (server 4xx/5xx), Http (transport), Json, Io, Dropped (queue full), Closed (client shut down).
  • Tests — cargo test runs the tiny_http mock-server suite: enqueue/flush, retries on 503, interval flush, tail, admin. cargo test --all-features adds 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.