Quickstart

What you need

The ai package installed (v4, v5, v6, or v7)
A Foglamp API key (starts with fl_), created in the dashboard or printed by the seed script when self-hosting

Not sure which AI SDK version you have? Run npm ls ai or check package.json. There are two setup paths, one for v4 to v6 and one for v7. Both produce the same traces.

1. Install

npm i foglamp

pnpm add foglamp

bun add foglamp

yarn add foglamp

2. Configure

Set your key in the environment:

.env

FOGLAMP_API_KEY=fl_your_key_here
# Only needed when self-hosting. The hosted service is the default.
FOGLAMP_INGEST_URL=http://localhost:4000/ingest

If FOGLAMP_API_KEY is not set, Foglamp does nothing: no traces are sent and nothing breaks. This makes it safe to keep the code in place in every environment.

3. Add it to your code

Pick the tab for your AI SDK version.

AI SDK v4 to v6
AI SDK v7 (beta)

Wrap the ai module once with wrap(), then use fog.with(...) to name your calls. The functions you get back have the AI SDK’s own types, so you 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);

const { generateText } = fog.with({ agentName: "summarizer" });

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

wrap() also covers the AI SDK’s agent classes, and fog.run(context, fn) lets you set context for a whole block of code at once. See AI SDK v4 to v6 (wrap) for details.

Pass the integration into each call’s telemetry.integrations array. Every call needs a traceName or an agentName. If you use workflowName, pass workflowRunId with it.

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 for 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,
      }),
    ],
  },
});

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

To trace every call without editing each one, register once with registerTelemetry(foglamp()). See the SDK overview.

4. Flush

On long-running servers (Node, Bun), Foglamp sends data automatically on a timer. In serverless functions, make sure the data is sent before the function returns:

await fog.flush();

See Runtimes and flushing for what each platform needs.

5. Look at the dashboard

Run your app, then open the dashboard. Your call shows up under Traces with its spans, tokens, cost, and timing. Calls that share a workflowRunId appear together on the Workflows page.

SDK reference

All options and integration fields.

Data model

How traces, spans, workflows, and runs fit together.

Get started

Core concepts

SDK

What you need

1. Install

2. Configure

3. Add it to your code

4. Flush

5. Look at the dashboard

SDK reference

Data model

​What you need

​1. Install

​2. Configure

​3. Add it to your code

​4. Flush

​5. Look at the dashboard

SDK reference

Data model

What you need

1. Install

2. Configure

3. Add it to your code

4. Flush

5. Look at the dashboard