Transport & Batching

The SDK batches events in memory and flushes them to the Trasys ingest API on a timer rather than sending one request per span. Most services never need to touch these settings — the defaults are production-tuned — but they're worth understanding if you're debugging data latency, memory usage, or gaps during an outage.

Flush intervals

createSdk({
  transport: {
    flushIntervalMs:        2000,  // traces + logs, default 2s
    metricExportIntervalMs: 15000, // metrics, default 15s
  },
});

Metrics flush on a separate, longer interval than traces/logs — they're less critical to be real-time and more expensive to send at high frequency. Lowering flushIntervalMs reduces the delay before a trace shows up in the dashboard at the cost of more frequent network requests; raising it does the opposite.

Batch size

createSdk({
  transport: {
    batchSize: 100, // default — flush immediately once this many events are queued
  },
});

Regardless of the flush interval, a batch is sent as soon as it reaches batchSize events — this caps memory growth during a traffic spike instead of waiting for the next timer tick.

Buffering during an outage

If the ingest API is unreachable, events aren't dropped immediately — they go into an in-memory ring buffer:

createSdk({
  transport: {
    maxBufferSize: 50000, // default — roughly 50MB of RAM
  },
});

When the buffer is full, the oldest events are dropped to make room for new ones — newest events are kept because they're the most relevant for debugging whatever's happening right now. This buffer doesn't persist across a process restart; if the process crashes or redeploys while the network is down, whatever's still in the buffer is lost.

Retry and backoff

createSdk({
  transport: {
    timeoutMs:    5000, // per-request timeout before it's treated as a failure
    maxRetries:   3,    // per batch, before the batch is dropped
    retryDelayMs: 1000, // initial delay, doubles each attempt
  },
});

Retries use exponential backoff: roughly 1s → 2s → 4s → up to a 60s cap. A batch that exhausts maxRetries is dropped rather than retried indefinitely — this keeps a prolonged outage from causing unbounded memory growth beyond what maxBufferSize already allows.

Graceful shutdown

The SDK registers handlers for SIGTERM, SIGINT, and beforeExit, and flushes whatever's currently buffered before the process exits — you don't need to call anything manually in most deployments. See Installation & Setup for the manual-shutdown pattern if your deployment needs one.

Next steps

• SDK Error Reference — what happens when the API key itself is invalid, as opposed to a transient network issue
• Metrics — metrics specifically use metricExportIntervalMs, not flushIntervalMs
• Installation & Setup — the full config reference