Batching & Delivery

@grounded/tracing batches completed traces in memory and sends them to /api/traces/batch.

This is a server-side delivery model, not a browser offline queue.

Defaults

const tracing = new GroundedTracing({
  publishableKey,
  flushAt: 20,
  flushIntervalMs: 5_000,
  timeoutMs: 15_000,
  maxRetries: 2,
});

Default behavior:

queue completed traces in memory
flush when the queue reaches flushAt
also flush on the background interval
retry transient failures

What Gets Queued

Only completed traces are queued. Partial spans are not streamed as they happen.

That means a trace is enqueued when you call:

await trace.end(...)

Retry Behavior

Flushes retry on:

429
5xx
retryable network errors

They do not retry indefinitely. If all attempts fail, the batch is pushed back onto the in-memory queue and the error is thrown.

`flush()`

Use flush() when you want immediate delivery:

await tracing.flush();

Good use cases:

tests
one-off scripts
before returning from a short-lived worker
after a critical user action

`shutdown()`

shutdown() stops the interval timer and flushes remaining traces.

await tracing.shutdown();

Recommended process hooks:

process.on('SIGTERM', async () => {
  await tracing.shutdown();
  process.exit(0);
});
 
process.on('SIGINT', async () => {
  await tracing.shutdown();
  process.exit(0);
});

Serverless And Short-Lived Jobs

For short-lived environments, prefer:

lower flushAt
flushIntervalMs: 0 or a very short interval
explicit flush() or shutdown() in the request or job lifecycle

Example:

const tracing = new GroundedTracing({
  publishableKey,
  flushAt: 1,
  flushIntervalMs: 0,
});
 
try {
  await runInvocation();
} finally {
  await tracing.shutdown();
}

What "Offline" Means Here

The queue is in memory only.

short interruptions are usually fine
long outages can still be retried while the process is alive
process restarts drop anything still buffered

If you need durable delivery, wrap the SDK with your own job or queue system.

Identity Masking