Quickstart

Instrument a Vercel AI SDK app and see your first trace.

Requirements

Foglamp works with every major version of the Vercel AI SDK — v4, v5, v6, and v7 (beta). You pick an instrumentation path by the version your app runs; both produce identical traces to the same backend.

• ai installed — any of v4, v5, v6, or v7
• A Foglamp API key (fl_…) — created in the dashboard, or printed by the seed script when self-hosting
• An ingest endpoint URL — https://ingest.foglamp.dev/ingest for hosted, or your own when self-hosting

Not sure which version you’re on? Run npm ls ai (or check the ai entry in package.json). The two paths share the same trace context, configuration, and flushing — only the call wiring differs.

1. Install

npm

npm i foglamp

2. Configure

Set your key and endpoint in the environment:

.env

FOGLAMP_API_KEY=fl_your_key_here
# Hosted default is used if unset. When self-hosting, point at your ingest API:
FOGLAMP_INGEST_URL=http://localhost:4000/ingest

If FOGLAMP_API_KEY is not set, the SDK is a silent no-op — your app runs exactly as before, with no spans recorded and nothing thrown. This makes it safe to leave instrumentation in place across every environment.

3. Instrument

How you attach Foglamp depends on your AI SDK version. Both paths capture the same traces — model steps, tool calls, tokens, cost, latency — and send them to the same endpoint. Pick the tab for the version your app runs.

AI SDK v4–v6

Wrap the ai module once with wrap() from foglamp/wrap, then bind a trace context with fog.with(...). The returned functions have the AI SDK’s own, fully-typed signatures — use them exactly as before.

import * as ai from "ai";
import { openai } from "@ai-sdk/openai";
import { wrap } from "foglamp/wrap";

const fog = wrap(ai);

// Bind a context; get the AI SDK's own signatures back, fully typed.
const { generateText } = fog.with({ agentName: "summarizer" });

const { text } = await generateText({
  model: openai("gpt-4o"),
  prompt: "Summarize the latest deploy.",
});

wrap() also returns drop-in ToolLoopAgent / Experimental_Agent classes, and fog.run(context, fn) sets run/session context ambiently with no parameter threading. See AI SDK v4–v6 (wrap) for the full surface.

AI SDK v7 (beta)

Attach the integration to individual generateText/streamText calls through v7’s telemetry.integrations array. Every call needs a traceName or an agentName; workflowName and workflowRunId are passed together.

import { foglamp } from "foglamp";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const fog = foglamp();

// One run of a workflow — reuse this id across every call in the run.
const runId = crypto.randomUUID();

const result = await generateText({
  model: openai("gpt-4o"),
  prompt: "Summarize the latest deploy.",
  telemetry: {
    integrations: [
      fog.integration({
        agentName: "summarizer",
        workflowName: "deploy-digest",
        workflowRunId: runId,
      }),
    ],
  },
});

// Or, for a one-off call that isn't an agent, just name it:
// fog.integration({ traceName: "summarize-deploy" })

To instrument every call without touching call sites, register once with registerTelemetry(foglamp()) — see the SDK overview.

4. Flush

In long-running servers (Node, Bun) the SDK flushes on an interval automatically. In serverless runtimes you must ensure the batch is sent before the function returns — see Runtimes & flushing.

await fog.flush();

5. See it in the dashboard

Run your app, then open the dashboard. Your call appears under Traces, with its spans, token usage, computed cost, and latency. Group related calls with a shared workflowRunId to see them on the Workflows timeline.

SDK reference

All configuration options and integration fields.

Data model

How traces, spans, workflows, and runs relate.