/// SDK — PYTHON
Python SDK STABLE
Synchronous, standard-library-only client — no requests, no pydantic.
Buffered shipping on a daemon thread, the full read/admin surface, and a
logging.Handler for drop-in instrumentation. Python 3.9+.
pip install ./sdks/python # from the repo python -m unittest discover -s tests # 20 tests
import duckgraph
client = duckgraph.Client("http://localhost:8080",
api_key="dgk_…", gzip=True, batch_size=512)
client.log("info", "myapp", "started on port %d", 8080) # buffered
client.send([duckgraph.Entry(service="myapp", message="now")]) # direct
rows = client.query(duckgraph.Query(min_level="error",
attrs={"env": "prod"}))
client.close() # or: with duckgraph.Client(...) as client:
Client
duckgraph.Client(base_url, **kwargs) starts the flusher thread.
Client.login(base_url, user, pass, **kwargs) (or the module-level
duckgraph.login) authenticates first and holds the dgs_
session token.
| Kwarg | Default | Purpose |
|---|---|---|
api_key | — | dgk_ API key — recommended for shippers |
token | — | dgs_ session token |
batch_size | 512 | Max entries per POST |
flush_interval | 2.0 | Buffer flush cadence, seconds |
queue_size | 8192 | Local buffer capacity |
gzip | False | Compress request bodies |
retries | 3 | Attempts on 429/5xx/network errors |
timeout | 30.0 | Per-request timeout, seconds |
on_error | — | Async send-failure callback |
opener | — | Custom urllib opener — proxies, handlers |
Ingest
| Method | Behaviour |
|---|---|
enqueue(entry) | Buffer one entry. Raises QueueFull when full, ClientClosed after close. |
log(level, service, msg, *args, host=, attrs=, ts=) | Enqueue sugar — %-formatting with args. |
send(entries) → int | POST immediately (chunks at 50k). Returns count accepted. |
flush(timeout=None) | Drain the queue synchronously. |
dropped | Property — entries rejected by a full queue. |
close(timeout=10) | Stop the thread and flush — also via with. |
Entry fields: ts (epoch/RFC3339, default server-now),
level, service (required), host,
message (required), attrs (dict).
logging handler
import logging, duckgraph
client = duckgraph.Client("http://localhost:8080", api_key="dgk_…")
logging.basicConfig(handlers=[
duckgraph.DuckgraphHandler(client, service="myapp")])
log = logging.getLogger(__name__)
log.info("request done", extra={"ms": 3200, "route": "/pay"})
Levels map DEBUG→debug, INFO→info, WARNING→warn, ERROR→error,
CRITICAL→fatal. extra={…} fields become attrs;
exc_info lands in attrs["exception"].
Query & read
| Method | Endpoint | Returns |
|---|---|---|
query(q) | GET /v1/logs | list[Row] newest-first |
query_post(q) | POST /v1/query | Same — better for large attr filters |
stats(window=None, bucket="1m") | GET /v1/stats | Stats — window accepts timedelta / seconds / "1h" |
services() | GET /v1/services | list[str] |
metrics() | GET /v1/metrics | IngestMetrics (reader+) |
system() | GET /v1/system | SystemInfo |
health() → bool | GET /healthz | Liveness — no auth |
me() | GET /v1/auth/me | Principal |
logout() | POST /v1/auth/logout | Revoke session |
tail(q) → Iterator[Row] | GET /v1/logs/tail | SSE generator — break to close |
for row in client.tail(duckgraph.Query(min_level="warn")):
print(row.level, row.service, row.message, row.attrs_json)
Query fields: from_ts/to_ts (datetime | epoch | RFC3339), levels,
min_level, services, hosts, search,
attrs, order_asc, limit, offset.
Row.attrs is the raw JSON string — row.attrs_json parses it.
Admin ADMIN ROLE
| Method | Endpoint |
|---|---|
list_users() | GET /v1/users |
create_user(name, password, role) | POST /v1/users |
update_user(name, role=, disabled=, password=) | PATCH /v1/users/{name} |
delete_user(name) | DELETE /v1/users/{name} |
list_api_keys() | GET /v1/apikeys |
create_api_key(name, role) → APIKey | POST /v1/apikeys — key.secret shown once |
revoke_api_key(id) | DELETE /v1/apikeys/{id} |
sql(statement) → SQLResult | POST /v1/sql — read-only |
Errors: APIError(status, message) for non-2xx,
QueueFull / ClientClosed for local state —
all under DuckgraphError.