> ## 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.

# 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](/self-hosting/overview)
* An ingest endpoint URL — `https://ingest.foglamp.dev/ingest` for hosted, or
  your own when self-hosting

<Info>
  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.
</Info>

## 1. Install

<CodeGroup>
  ```bash npm theme={null}
  npm i foglamp
  ```

  ```bash pnpm theme={null}
  pnpm add foglamp
  ```

  ```bash bun theme={null}
  bun add foglamp
  ```

  ```bash yarn theme={null}
  yarn add foglamp
  ```
</CodeGroup>

## 2. Configure

Set your key and endpoint in the environment:

```bash .env theme={null}
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
```

<Info>
  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.
</Info>

## 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.

<Tabs>
  <Tab title="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.

    ```ts theme={null}
    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)](/sdk/wrap) for the full
    surface.
  </Tab>

  <Tab title="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.

    ```ts theme={null}
    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](/sdk/overview).
  </Tab>
</Tabs>

## 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](/sdk/runtimes).

```ts theme={null}
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.

<CardGroup cols={2}>
  <Card title="SDK reference" icon="code" href="/sdk/overview">
    All configuration options and integration fields.
  </Card>

  <Card title="Data model" icon="sitemap" href="/concepts/data-model">
    How traces, spans, workflows, and runs relate.
  </Card>
</CardGroup>