Configuration

Every option accepted by foglamp().

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 on the next call, so a crashed generation can’t leak its spans.
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),
});