Configuration

foglamp(config?) accepts the following options. Every field is optional, and the same options apply to the v4–v6 entry point — wrap(ai, config) takes them all, plus a wrap-time context (see wrap).

const fog = foglamp({
  apiKey: process.env.FOGLAMP_API_KEY,
  endpoint: process.env.FOGLAMP_INGEST_URL,
  flushIntervalMs: 5000,
  maxBatchTraces: 50,
  maxBatchSpans: 500,
  maxPayloadChars: 100_000,
  recordInputs: true,
  recordOutputs: true,
  debug: false,
  onError: (err) => console.error(err),
});

Options

Option	Type	Default	Description
`apiKey`	string	`FOGLAMP_API_KEY`	Your `fl_…` key. Unset → collector disabled.
`endpoint`	string	`https://ingest.foglamp.dev/ingest`	Ingest URL. Set when self-hosting.
`flushIntervalMs`	number	`5000`	How often the batch is flushed in long-running runtimes.
`maxBatchTraces`	number	`50`	Flush early once this many traces are buffered.
`maxBatchSpans`	number	`500`	Flush early once this many spans are buffered.
`maxQueuedSpans`	number	`5000`	Hard cap on spans buffered in memory (e.g. when ingest is unreachable). Past it, the oldest traces are dropped and `onError` fires.
`maxTraceAgeMs`	number	`600_000`	Traces still open after this (10 min) are finalized as `abandoned` (an error) on the next call, so a crashed generation can’t leak its spans. A cleanly cancelled stream is different — AI SDK v7’s `onAbort` finalizes it promptly with the first-class `aborted` status instead of waiting for this timeout.
`maxPayloadChars`	number	`100_000`	Per-field cap for `input`/`output`; longer values are truncated.
`recordInputs`	boolean	`true`	Capture prompt/input text.
`recordOutputs`	boolean	`true`	Capture completion/output text.
`waitUntil`	function	—	Serverless flush hook. Auto-detected on Vercel, Lambda, and edge; pass `ctx.waitUntil` on Cloudflare Workers. See Runtimes.
`fetch`	function	global `fetch`	Custom fetch implementation.
`debug`	boolean	`false`	Log batching/flush activity.
`onError`	function	—	Called on transport/serialization errors instead of throwing.

The ingest contract caps any single input or output field at 1,000,000 characters. maxPayloadChars (default 100,000) truncates earlier so payloads stay small — raise it only if you need fuller logs and can afford the bytes. A value above 1,000,000 is silently clamped to the contract cap.

Privacy: dropping prompt/response text

To record traces, costs, and latency without ever sending prompt or completion text, disable capture:

const fog = foglamp({
  recordInputs: false,
  recordOutputs: false,
});

Token usage and cost are still computed — they come from the provider’s usage report, not from the text.

Error handling

The collector never throws into your application path. Transport or serialization failures are routed to onError (if provided) or swallowed. Enable debug to trace batching and flush behavior during development.

const fog = foglamp({
  debug: process.env.NODE_ENV !== "production",
  onError: (err) => reportToSentry(err),
});

Get started

Core concepts

SDK

Options

Privacy: dropping prompt/response text

Error handling

​Options

​Privacy: dropping prompt/response text

​Error handling

Options

Privacy: dropping prompt/response text

Error handling