/// DEVELOPER DOCUMENTATION
Docs.
One service, four SDKs, one contract. Every client ships logs through a buffered background worker — batch by size or interval, retry transient failures, drop loudly when the queue fills — and reads back through the same query, stats, live-tail and admin surface.
SDK status
| Language | Status | Source | Logger integration |
|---|---|---|---|
| Go | STABLE | sdk/ — module duckgraph/sdk |
log/slog handler |
| Python | STABLE | sdks/python/ |
logging.Handler |
| TypeScript | STABLE | sdks/typescript/ |
DuckgraphLogger |
| Rust | STABLE | sdks/rust/ |
log + tracing features |
Pick a language
Stdlib-only client. Enqueue + background batching, slog.Handler integration, channel-based live-tail. Mirrors the server's own implementation language.
Synchronous, standard library only, Python 3.9+. logging.Handler integration, generator-based tail, context-manager lifecycle.
Zero-dependency ESM client, Node 18+ and edge runtimes. Async-iterator tail, DuckgraphLogger, pluggable fetchFn.
Synchronous client on ureq — cheap-to-clone Client sharing one batching worker. log and tracing integrations behind feature flags.
The shared contract
All SDKs implement the same behaviour so semantics don't change when you switch languages:
- Buffered ingest —
enqueuewrites to a local queue; a background worker POSTs batches ofbatch_size(512) or everyflush_interval(2s), whichever comes first. - Loud drops — a full queue raises/returns the SDK's queue-full error and increments
dropped. Registeron_errorto catch async send failures. - Retries — 429, 5xx and network errors retry with exponential backoff (default 3 attempts). 4xx fails immediately.
- Gzip — optional request-body compression (
Content-Encoding: gzip). - Live-tail — Server-Sent-Events stream, best-effort delivery. Channels in Go, generators in Python/Rust, async iterators in TypeScript.
- 50k cap — the server accepts at most 50,000 entries per POST; SDKs chunk
sendautomatically.
Authentication
Two credential types, one header — Authorization: Bearer <token>:
| Credential | Prefix | Use for |
|---|---|---|
| API key | dgk_… | Shippers and automation — created by an admin via /v1/apikeys or the settings UI, scoped to a role, secret shown once. |
| Session token | dgs_… | Interactive use — returned by /v1/auth/login, revoked by logout. |
Roles are hierarchical: reader < writer < admin. See the
HTTP API reference for the role each endpoint requires.
60-second quickstart
# sign in → session token
TOKEN=$(curl -s localhost:8080/v1/auth/login \
-H 'content-type: application/json' \
-d '{"username":"admin","password":"…"}' | jq -r .token)
# ship one entry
curl -s localhost:8080/v1/logs \
-H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '[{"service":"myapp","level":"info","message":"hello duckgraph"}]'
# read it back
curl -s "localhost:8080/v1/logs?service=myapp&limit=1" \
-H "authorization: Bearer $TOKEN"
Prefer a real client? Jump to Go, Python, TypeScript or Rust — or call the API directly per the HTTP reference.