Patterns
Delivery Model

Delivery Model

The current SDK does not implement streaming trace ingest.

That is intentional.

What Happens Today

@grounded/tracing only sends completed traces to:

POST /api/traces/batch

This means:

  • spans can be recorded incrementally in memory
  • events can be added during execution
  • the network write happens after trace.end()

Why This Design

Grounded is optimizing for:

  • simple server integration
  • lower write amplification
  • predictable retries
  • clean trace normalization into sessions

If Your App Streams Tokens

Your app can still stream tokens to users. The SDK just records the final trace after the request is done.

A good pattern is:

  1. stream tokens to the caller however you already do
  2. keep relevant intermediate state in local memory
  3. call trace.end() with the final output
  4. flush on a reasonable cadence

Jobs Are Also Poll-Based In The SDK

The backend may expose richer internal streaming or trace-summary routes, but the SDK currently emphasizes:

  • jobs.wait() polling
  • jobs.steps() for ordered step history
  • jobs.summary() for structured summaries

So the current integration style is:

  • completed traces for instrumentation
  • polling for long-running Grounded jobs
Errors, Retries, and TimeoutsRetrieval Tracing