DUCKGRAPH® LOG INGESTION UNIT
SYS.OK REV 1.0

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

GOQUICKSTART
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.

OptionDefaultPurpose
WithAPIKey(key)—dgk_ API key — recommended for shippers
WithToken(tok)—dgs_ session token
WithHTTPClient(hc)30s timeoutSwap transport — proxies, TLS, timeouts
WithBatchSize(n)512Max entries per POST
WithFlushInterval(d)2sBuffer flush cadence
WithQueueSize(n)8192Local buffer capacity
WithGzip()offCompress request bodies
WithRetries(n)3Attempts on 429/5xx/network errors
WithOnError(fn)—Async send-failure callback

Ingest

MethodBehaviour
Enqueue(e) errorBuffer 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) errorDrain the queue synchronously.
Dropped() int64Entries rejected by a full queue.
Close(ctx) errorStop 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

GOSLOG
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

MethodEndpointReturns
Query(ctx, q)GET /v1/logs[]Row newest-first
QueryPost(ctx, q)POST /v1/querySame — 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/mename, role
Tail(ctx, q)GET /v1/logs/tail(<-chan Row, <-chan error) SSE stream
GOTAIL
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

MethodEndpoint
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) *APIKeyPOST /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}.