Configuration

foglamp(config?) accepts the options below. Every field is optional. The v4 to v6 entry point takes the same options: wrap(ai, config) accepts them all, plus a context for defaults (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,
  recordSystemPrompt: true,
  debug: false,
  onError: (err) => console.error(err),
});

Options

Option	Type	Default	Description
`apiKey`	string	`FOGLAMP_API_KEY`	Your `fl_...` key. If unset, the collector is off.
`endpoint`	string	`https://ingest.foglamp.dev/ingest`	Where to send data. Set this when self-hosting.
`flushIntervalMs`	number	`5000`	How often batches are sent on long-running servers.
`maxBatchTraces`	number	`50`	Send early once this many traces are buffered.
`maxBatchSpans`	number	`500`	Send early once this many spans are buffered.
`maxQueuedSpans`	number	`5000`	Max spans held in memory (for example when ingest is unreachable). Past it, the oldest traces are dropped and `onError` fires.
`maxTraceAgeMs`	number	`600_000`	A trace still open after this long (10 minutes) is closed as `abandoned` and counted as an error, so a crashed generation can’t leak spans. A cleanly cancelled stream is handled right away instead, via the `aborted` status.
`maxPayloadChars`	number	`100_000`	Max length for each `input`/`output` field. Longer values are cut off.
`recordInputs`	boolean	`true`	Capture prompt text.
`recordOutputs`	boolean	`true`	Capture response text.
`recordSystemPrompt`	boolean	`true`	Capture the system prompt (`system`, or an agent’s `instructions`) on the run. It powers the System prompt section and prompt versions. Also off when `recordInputs` is off.
`waitUntil`	function	none	Serverless flush hook. Detected automatically on Vercel and Lambda; pass `ctx.waitUntil` on Cloudflare Workers. See Runtimes.
`fetch`	function	global `fetch`	Custom fetch implementation.
`debug`	boolean	`false`	Log batching and flush activity.
`onError`	function	none	Called on transport or serialization errors instead of throwing.

The ingest API caps any single input or output field at 1,000,000 characters. maxPayloadChars (default 100,000) cuts off earlier to keep payloads small. Raise it only if you need fuller logs. Values above 1,000,000 are clamped to that cap.

Privacy: keeping text out

To record traces, cost, and timing without ever sending prompt or response text, turn capture off:

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

Token counts and cost still work. They come from the provider’s usage report, not from the text. To keep the conversation but drop only the system prompt (for example when it embeds proprietary instructions), set recordSystemPrompt: false. Generation settings (temperature, max output tokens, …) and provider warnings are always recorded as span metadata; they contain no prompt text.

Error handling

The collector never throws into your app. Failures go to onError if you provide one, and are otherwise ignored. Turn on debug to watch batching and flushing during development.

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

Get started

Core concepts

SDK

Options

Privacy: keeping text out

Error handling

​Options

​Privacy: keeping text out

​Error handling

Options

Privacy: keeping text out

Error handling