DUCKGRAPH® LOG INGESTION UNIT
SYS.OK REV 1.0

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

SHELLINSTALL
pip install ./sdks/python          # from the repo
python -m unittest discover -s tests  # 20 tests
PYTHONQUICKSTART
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.

KwargDefaultPurpose
api_key—dgk_ API key — recommended for shippers
token—dgs_ session token
batch_size512Max entries per POST
flush_interval2.0Buffer flush cadence, seconds
queue_size8192Local buffer capacity
gzipFalseCompress request bodies
retries3Attempts on 429/5xx/network errors
timeout30.0Per-request timeout, seconds
on_error—Async send-failure callback
opener—Custom urllib opener — proxies, handlers

Ingest

MethodBehaviour
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) → intPOST immediately (chunks at 50k). Returns count accepted.
flush(timeout=None)Drain the queue synchronously.
droppedProperty — 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

PYTHONLOGGING
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

MethodEndpointReturns
query(q)GET /v1/logslist[Row] newest-first
query_post(q)POST /v1/querySame — better for large attr filters
stats(window=None, bucket="1m")GET /v1/statsStats — window accepts timedelta / seconds / "1h"
services()GET /v1/serviceslist[str]
metrics()GET /v1/metricsIngestMetrics (reader+)
system()GET /v1/systemSystemInfo
health() → boolGET /healthzLiveness — no auth
me()GET /v1/auth/mePrincipal
logout()POST /v1/auth/logoutRevoke session
tail(q) → Iterator[Row]GET /v1/logs/tailSSE generator — break to close
PYTHONTAIL
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

MethodEndpoint
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) → APIKeyPOST /v1/apikeys — key.secret shown once
revoke_api_key(id)DELETE /v1/apikeys/{id}
sql(statement) → SQLResultPOST /v1/sql — read-only

Errors: APIError(status, message) for non-2xx, QueueFull / ClientClosed for local state — all under DuckgraphError.