Skip to main content
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:
SettingDefaultEffect
flushIntervalMs2000Background flush every 2 seconds
maxBatchSize25Max events per POST /v1/events
maxQueueSize5000Max queued events before drop policy applies
retryAttempts3Retries on failed flush
retryBaseDelayMs250Base delay between retries
queueDropPolicydrop_oldestDrop oldest or newest when queue is full
queueStoragePathnonePersist queue to disk for durability
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

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: 
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

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

​
Idempotency

Provide a deduplication key to avoid duplicate events on retry: 
queueIdempotencyKey: (event) => event.eventId,

​
Next steps

Diagnose your setup

Doctor and queue health checks.

Redact secrets

Strip sensitive data from events.