SDK overview

The foglamp() collector and its integration methods.

The foglamp package has two entry points, one per AI SDK generation. Both batch spans and flush them to your ingest endpoint, and both share the same trace-context fields, fog.run(), configuration, and flushing — they differ only in how they attach to your calls.

wrap() — AI SDK v4–v6

Wraps the ai module for the stable v4, v5, and v6 lines.

foglamp() — AI SDK v7

The native telemetry-integrations collector. Documented below.

This page documents the v7 foglamp() collector; the v4–v6 wrap() API has its own reference. foglamp() returns a collector that batches spans and produces telemetry integrations you attach to AI SDK v7 calls.

import { foglamp } from "foglamp";

const fog = foglamp();

Whichever entry point you use, the SDK carries a single small runtime dependency (uuidv7) and never forces a particular version of zod on your project — the wire types are a hand-written, zod-free mirror of the contract, so ai is the only required peer dependency (ai@^4 || ^5 || ^6 || ^7.0.0-beta.1).

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 fog = 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

fog.integration(context)

Returns a telemetry integration to pass into a call’s telemetry.integrations array (AI SDK v7 also accepts the legacy experimental_telemetry alias). The context — a required argument — labels every span the call produces; calling it without a traceName or agentName throws immediately (at setup, not inside the call).

fog.integration({
  agentName: "summarizer",
  workflowName: "deploy-digest",
  workflowRunId: run.id,
  sessionId: user.threadId,
  metadata: { environment: "production", region: "us-east-1" },
});

// A one-off call that isn't an agent — name it instead:
fog.integration({ traceName: "classify-email" });

Context field	Type	Notes
traceName	string	label for a one-off call; required if agentName is absent
agentName	string	the actor responsible for the call; required if traceName is absent
workflowName	string	the named process; pass with workflowRunId
workflowRunId	string	groups traces into one run; pass with workflowName
sessionId	string	ties traces to one conversation
metadata	Record<string, string | number | boolean>	free-form labels; values are coerced to strings on the wire

traceName or agentName is required (both is fine — the display label is traceName ?? agentName). workflowName and workflowRunId must be passed together. Both rules are enforced at compile time and rechecked at ingest.

fog.flush()

Sends any buffered spans immediately and resolves when the request completes. Call this before a serverless function returns. Safe to call when the collector is disabled (resolves immediately).

await fog.flush();

fog.shutdown()

Stops the flush timer and drains everything, including traces enqueued while a flush was already in flight. Use on graceful process shutdown in long-running servers.

process.on("SIGTERM", async () => {
  await fog.shutdown();
});

flush() vs shutdown() — flush() is a per-request drain: the background timer keeps running and the collector stays usable. shutdown() is terminal: it stops the timer and loops until the queue is truly empty. Use flush() at the end of a serverless handler; use shutdown() exactly once when the process exits — calling only flush() there can strand traces enqueued mid-flush.

Registration paths

Per-call

Pass fog.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.