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

> Add Foglamp to a Vercel AI SDK app and see your first trace.

## 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](/self-hosting/overview)

<Info>
  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.
</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 in the environment:

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

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

## 3. Add it to your code

Pick the tab for your AI SDK version.

<Tabs>
  <Tab title="AI SDK v4 to v6">
    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.

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

  <Tab title="AI SDK v7 (beta)">
    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.

    ```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 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](/sdk/overview).
  </Tab>
</Tabs>

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

```ts theme={null}
await fog.flush();
```

See [Runtimes and flushing](/sdk/runtimes) 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.

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

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