Reliable telemetry

Tune the event queue, persist to disk, and shut down gracefully so no telemetry is lost.

Your agent runs in production, a worker, or a serverless function. You need telemetry to reach Apie reliably — even under load, network blips, or process shutdown.

Queue behavior

Events are enqueued in memory (or on disk) and flushed in batches:

Setting	Default	Effect
flushIntervalMs	2000	Background flush every 2 seconds
maxBatchSize	25	Max events per POST /v1/events
maxQueueSize	5000	Max queued events before drop policy applies
retryAttempts	3	Retries on failed flush
retryBaseDelayMs	250	Base delay between retries
queueDropPolicy	drop_oldest	Drop oldest or newest when queue is full
queueStoragePath	none	Persist queue to disk for durability

TypeScript

const apie = new Apie({
  agent: { key: "my-agent", name: "My Agent" },
  flushIntervalMs: 1000,
  maxBatchSize: 50,
  queueStoragePath: "/var/lib/apie/queue",
  queueDropPolicy: "drop_oldest",
  onError: "warn",
});

Flush on demand

TypeScript

await apie.flush();

withRun / with_run flushes before completing a run. Call flush() explicitly in serverless handlers before returning.

Graceful shutdown

Always shut down the client when your process exits:

TypeScript

await apie.shutdown();

shutdown() stops the flush timer and sends remaining queued events.

In AWS Lambda, Vercel Functions, or other serverless runtimes, call flush() at the end of every handler. The process may freeze before the next background flush.

Queue diagnostics

TypeScript

const diagnostics = apie.queueDiagnostics();
console.log(diagnostics);

Idempotency

Provide a deduplication key to avoid duplicate events on retry:

TypeScript

queueIdempotencyKey: (event) => event.eventId,

Next steps

Diagnose your setup

Doctor and queue health checks.

Redact secrets

Strip sensitive data from events.