gpumon-writer — telemetry & ledger HTTP API

Why this exists / when to use what

gpumon-writer is the single writer service for federation state. Everything that needs durable state — GPU samples, LLM call records, OCR job rows, workload registrations, project metadata, cooldowns, quality flags — goes through this one process. Its primary backend is ParadeDB (Postgres) via PG_DSN: heavy aggregations run as ordinary async SQL, so Bun's single thread never stalls ~8s on a multi-GB scan (the old SQLite behavior that drove 137 crash-loops). When PG_DSN is unset it falls back to legacy single-writer bun:sqlite (gpumon.db) — a one-line-env rollback; both backends expose the same call surface. Read paths (the /api/* GETs) hit the same backend through this same service.

Call the writer when: you need to persist something (telemetry, OCR job state, workload), or when you need to read aggregated state for a dashboard or audit. If you want to make an LLM call go through ingress, not the writer. If you want to enqueue work across machines, talk to the broker.

Addresses

The writer is pinned to node-eleven (single writer service). All callers across the swarm reach the same process — and therefore the same ParadeDB backend — via the published swarm-ingress port. Auth is none on LAN.

Endpoint table

GPU telemetry

LLM call telemetry

The two-phase pattern (/start → /finish) is what ingress uses internally; you only need to call these directly if you're routing around ingress (e.g. calling Anthropic) and still want the call to appear on the dashboard.

Workloads

A workload groups N LLM calls into one logical "job" (e.g. "summarize this 10-K" = 1 workload, ~12 LLM calls). Register at the start, complete at the end; the dashboard renders an in-flight tile per active workload.

Projects

OCR jobs (wave-1 federation queue)

These are the writer-side ledger for OCR jobs. The producer (gpumon-ocr-api) calls /start on POST /jobs. The worker (gpumon-ocr-worker) calls /finish on success / partial-success or /fail after MAX_ATTEMPTS exhausts. All three are idempotent so the dual-write window during a redeploy doesn't corrupt state, and terminal states (done, exhausted, error) are sticky — a retried /start cannot un-finish a job.

Most integrators use gpumon-ocr-api (see ocr-api.md) rather than these endpoints directly. Talk to the writer's OCR endpoints directly only if you're writing a new producer / worker pair.

Cooldowns

Quality / corruption

Health / observability

SSE live stream

Event shape: event: <kind>\ndata: <json>\n\n. Kinds include hello, gpu-sample, llm-call, ocr-job, workload-complete. The dashboard consumes this; any client that wants to live-tail can too.

curl examples

Open a workload, call ingress, close the workload

# 1. Open
WORKLOAD=$(curl -s http://node-eleven:2289/workloads \
  -H 'content-type: application/json' \
  -d "{\"client_id\":\"edgar-summarizer\",\"workload\":\"10K-summary\",
        \"started_at\":$(date +%s),\"ttl_s\":3600,
        \"expected_calls\":12,\"stages\":[\"chunk\",\"summarize\",\"verify\"]}" \
  | jq -r '.workload_id')

# 2. Use $WORKLOAD as x-gpumon-workload-id on every ingress call
#    (see ingress.md)

# 3. Close
curl -X POST http://node-eleven:2289/workloads/$WORKLOAD/complete

List recent OCR jobs

curl 'http://node-eleven:2289/api/ocr/jobs?limit=50' | jq '.jobs[] | {id,filename,status}'

Tail the live stream

curl -N http://node-eleven:2289/stream

Bun fetch example

// Record an LLM call we made directly (didn't go through ingress).
const t0 = Date.now();
const start = await fetch("http://node-eleven:2289/llm-calls/start", {
  method: "POST",
  headers: {"content-type":"application/json"},
  body: JSON.stringify({
    project_id: "claude-mem",
    caller_service: "observation-extractor",
    model: "claude-opus-4-7",
    pool: "anthropic-direct",
    upstream_host: "api.anthropic.com",
    prompt: "Summarize this transcript ...",
    workflow_stage: "extract",
  }),
});
const {request_id} = await start.json();

// ... actually call the LLM ...
const response = "...";

await fetch("http://node-eleven:2289/llm-calls/finish", {
  method: "POST",
  headers: {"content-type":"application/json"},
  body: JSON.stringify({
    request_id,
    status: "ok",
    latency_ms: Date.now() - t0,
    prompt_tokens: 1024, completion_tokens: 256, total_tokens: 1280,
    cost_usd: 0.012,
    response,
    upstream_model: "claude-opus-4-7",
  }),
});

End-to-end walkthrough — record an LLM call's outcome

This is the path ingress itself uses; you only do it manually when routing around ingress.

caller ─► ingress  POST /v1/chat/completions
                   │  parses x-gpumon-* headers
                   ▼
caller ◀──ingress  ───► writer  POST /llm-calls/start
                                ◀── {request_id}
        (response)               ▲
                                 │ writer SSE: event: llm-call
ingress  ◀── upstream LLM        │  data: {request_id, status:"in_flight", ...}
         ─► writer  POST /llm-calls/finish
                    ◀── {ok:true}
                    ▲
                    │ writer SSE: event: llm-call
                    │  data: {request_id, status:"ok", latency_ms, ...}
                    ▼
                  dashboard renders the row

The dashboard's live stream subscribes to GET /stream and re-renders on every event. Two-phase write keeps the row visible while in flight — useful for spotting hangs.

Cross-references

• LLM call originators: ingress.md
• OCR job producer: ocr-api.md
• Queue-driven workers that ledger via this writer: client-pattern.md