DUCKGRAPH® LOG INGESTION UNIT
SYS.OK REV 1.0

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

LanguageStatusSourceLogger 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

The shared contract

All SDKs implement the same behaviour so semantics don't change when you switch languages:

  • Buffered ingest — enqueue writes to a local queue; a background worker POSTs batches of batch_size (512) or every flush_interval (2s), whichever comes first.
  • Loud drops — a full queue raises/returns the SDK's queue-full error and increments dropped. Register on_error to 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 send automatically.

Authentication

Two credential types, one header — Authorization: Bearer <token>:

CredentialPrefixUse for
API keydgk_…Shippers and automation — created by an admin via /v1/apikeys or the settings UI, scoped to a role, secret shown once.
Session tokendgs_…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

SHELLCURL
# 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.