Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.foglamp.dev/llms.txt

Use this file to discover all available pages before exploring further.

The foglamp package exposes a single factory, foglamp(), which returns a collector. The collector batches spans and flushes them to your ingest endpoint, and produces telemetry integrations you attach to AI SDK calls. 
import { foglamp } from "foglamp";

const wt = foglamp();
The SDK requires AI SDK v7 and declares ai@7 as a peer dependency. It ships zero runtime dependencies of its own and never forces a particular version of zod on your project.

​
foglamp(config?)

Creates a collector. All configuration is optional; sensible defaults apply and missing credentials disable the collector silently. See Configuration for the full option table. 
const wt = foglamp({
  apiKey: process.env.FOGLAMP_API_KEY,
  endpoint: process.env.FOGLAMP_INGEST_URL,
  flushIntervalMs: 5000,
});
If apiKey is unset (and not in the environment), the collector is disabled: integrations become no-ops, nothing is sent, and nothing is thrown.

​
Collector methods

​
wt.integration(context?)

Returns a telemetry integration to pass into a call’s experimental_telemetry.integrations array. The optional context labels every span the call produces. 
wt.integration({
  agentName: "summarizer",
  workflowName: "deploy-digest",
  workflowRunId: run.id,
  sessionId: user.threadId,
  metadata: { environment: "production", region: "us-east-1" },
});
Context fieldTypeNotes
agentNamestringthe actor responsible for the call
workflowNamestringthe named process
workflowRunIdstringgroups traces into one run
sessionIdstringties traces to one conversation
metadataRecord<string, string | number | boolean>free-form labels

​
wt.flush()

Sends any buffered spans immediately and resolves when the request completes. Call this before a serverless function returns, or on shutdown. Safe to call when the collector is disabled (resolves immediately). 
await wt.flush();

​
wt.shutdown()

Stops the flush timer and performs a final flush. Use on graceful process shutdown in long-running servers. 
process.on("SIGTERM", () => wt.shutdown());

​
Registration paths

Per-call

Pass wt.integration(...) into a single call’s telemetry. Fully typed, and wins over any global registration.

Global

registerTelemetry(foglamp()) instruments every call. Reads functionId as agentName and reserved keys from telemetry.metadata.
Next: tune batching and capture in Configuration, and make sure spans actually leave serverless functions in Runtimes & flushing.