Reliability & serverless

The SDK’s contract is fail-open, always: if Glassray is down, slow, or misconfigured - or the SDK itself has a bug - the worst case is lost telemetry. Your agent is never blocked, never slowed on the critical path, and never crashed by tracing.

The guarantees

Every public method is internally guarded; SDK errors go to a rate-limited warning (or your onWarn), and your return value or exception passes through untouched.
A missing or invalid API key disables sending, not your agent.
No timer or socket ever holds the process open - everything is unref’d.
Invalid configuration warns and disables; it never throws.
The SDK sends nothing but your traces - zero phone-home.

Delivery model

A trace is buffered in memory while it runs and POSTed once, when its root settles - on success or on throw. One trace, one request, off the critical path. This matches the ingest contract (whole trace per request - see Bring your own OTel for why that matters).

The bounds

Documented because the numbers are the trust signal - this is exactly how much memory, time, and retry traffic the SDK will ever cost you:

Bound	Value
Outbound queue	100 traces / 20 MiB - overflow drops the oldest trace and warns once
Request timeout	10 s
Compression	gzip for payloads ≥ 8 KiB
`429`	Honors `Retry-After`, pauses the sender for the window
`503` / network	Jittered backoff, max 2 retries
Other 4xx	Dropped immediately - retrying client errors only amplifies outages
`401` / `403`	Warn once, then mute the sender (fix the key, restart)
Per-field cap	32 KiB per content attribute - truncated with an explicit `…[glassray:truncated N bytes]` marker
Whole-trace cap	4 MiB soft cap - largest span contents truncate first; structure, timing, and tokens always survive

Everything dropped is accounted for:

glassray.stats(); // { sent, dropped: { byReason }, queued }

Serverless

Because a trace POSTs at root settle, a long-lived process needs nothing. Platforms that freeze or kill the process right after the response need one flush call:

Runtime	What you need
Long-lived Node (server, worker)	Nothing.
Vercel	`waitUntil(glassray.flush())` after the response.
AWS Lambda	`await glassray.flush()` before returning from the handler.
Cloudflare Workers	`ctx.waitUntil(glassray.flush())` - needs the `nodejs_compat` flag; edge runtimes are early, Node is the tested path.

// Vercel route handler
import { waitUntil } from "@vercel/functions";

export const POST = async (req: Request) => {
  const result = await glassray.trace("handle-request", async (t) => runAgent(req, t));
  waitUntil(glassray.flush());
  return Response.json(result);
};

Traces cut off mid-run or missing entirely on serverless is almost always a missing flush - it’s the first item on the troubleshooting checklist.

Get started

Glassray CLI

Coach (local)

Concepts

Trace sources

Glassray SDK

Integrations

Explore

Reliability & serverless

The guarantees

Delivery model

The bounds

Serverless

​The guarantees

​Delivery model

​The bounds

​Serverless

The guarantees

Delivery model

The bounds

Serverless