/// SDK — GO
Go SDK STABLE
The reference client — standard library only, no third-party deps.
Buffered shipping with a background flusher, full query/admin surface,
and a log/slog handler so existing instrumentation ships
without changes. Lives at sdk/ (module duckgraph/sdk).
import "duckgraph/sdk"
c, _ := sdk.New("http://localhost:8080",
sdk.WithAPIKey("dgk_…"),
sdk.WithGzip(),
)
defer c.Close(context.Background())
c.Logf("info", "myapp", "started on port %d", 8080) // buffered
c.Send(ctx, []sdk.Entry{{Service: "myapp", Message: "now"}}) // direct
rows, _ := c.Query(ctx, sdk.Query{MinLevel: "error",
Attrs: map[string]string{"env": "prod"}})
Client
sdk.New(baseURL, …Option) starts the background flusher immediately;
sdk.Login(ctx, baseURL, user, pass, …Option) authenticates first and
returns a client holding the dgs_ session token.
| Option | Default | Purpose |
|---|---|---|
WithAPIKey(key) | — | dgk_ API key — recommended for shippers |
WithToken(tok) | — | dgs_ session token |
WithHTTPClient(hc) | 30s timeout | Swap transport — proxies, TLS, timeouts |
WithBatchSize(n) | 512 | Max entries per POST |
WithFlushInterval(d) | 2s | Buffer flush cadence |
WithQueueSize(n) | 8192 | Local buffer capacity |
WithGzip() | off | Compress request bodies |
WithRetries(n) | 3 | Attempts on 429/5xx/network errors |
WithOnError(fn) | — | Async send-failure callback |
Ingest
| Method | Behaviour |
|---|---|
Enqueue(e) error | Buffer one entry. ErrDropped when the queue is full, ErrClosed after close. |
Logf(level, svc, fmt, …) | Enqueue sugar with Sprintf formatting. |
Send(ctx, []Entry) (int, error) | POST immediately, bypassing the buffer. Returns count accepted. |
Flush(ctx) error | Drain the queue synchronously. |
Dropped() int64 | Entries rejected by a full queue. |
Close(ctx) error | Stop the worker and flush — idempotent. |
Entry fields: TS (default server-now), Level
(debug|info|warn|error|fatal), Service (required), Host,
Message (required), Attrs (map[string]any).
slog handler
logger := slog.New(sdk.NewSlogHandler(c, &sdk.SlogOptions{
Service: "myapp",
Host: host,
Level: slog.LevelInfo,
OnDrop: func() { dropped.Add(1) },
}))
slog.SetDefault(logger)
slog.Info("request done", "ms", 3200, "route", "/pay")
sdk.FlushSlog(c) // graceful shutdown
Levels map Debug→debug, Info→info, Warn→warn, Error+→error. Record
attrs become entry attrs; WithGroup nests them. A full queue
calls OnDrop instead of blocking your goroutine.
Query & read
| Method | Endpoint | Returns |
|---|---|---|
Query(ctx, q) | GET /v1/logs | []Row newest-first |
QueryPost(ctx, q) | POST /v1/query | Same — better for large attr filter sets |
Stats(ctx, window, bucket) | GET /v1/stats | *Stats totals + per-level + per-service + time series |
Services(ctx) | GET /v1/services | []string distinct service names |
Me(ctx) | GET /v1/auth/me | name, role |
Tail(ctx, q) | GET /v1/logs/tail | (<-chan Row, <-chan error) SSE stream |
rows, errs := c.Tail(ctx, sdk.Query{MinLevel: "warn"})
for {
select {
case r, ok := <-rows:
if !ok { return }
fmt.Println(r.Level, r.Service, r.Message)
case err := <-errs:
return // stream error or ctx done
}
}
Query fields: From/To (time.Time),
Levels, MinLevel, Services, Hosts,
Search, Attrs (exact match, dots nest), OrderAsc,
Limit, Offset.
Surface gap: the Go client doesn't yet wrap
/v1/metrics, /v1/system, /v1/sql or
/healthz — call them directly per the
HTTP reference (the other SDKs already include them).
Admin ADMIN ROLE
| Method | Endpoint |
|---|---|
ListUsers(ctx) | GET /v1/users |
CreateUser(ctx, name, pass, role) | POST /v1/users |
UpdateUser(ctx, name, role*, disabled*, pass) | PATCH /v1/users/{name} |
DeleteUser(ctx, name) | DELETE /v1/users/{name} |
ListAPIKeys(ctx) | GET /v1/apikeys |
CreateAPIKey(ctx, name, role) *APIKey | POST /v1/apikeys — key.Secret shown once |
RevokeAPIKey(ctx, id) | DELETE /v1/apikeys/{id} |
Roles are admin, writer, reader.
Non-2xx responses return *APIError{Status, Message}.