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

# Troubleshooting

> Why you might not see traces, and how to fix it.

Foglamp fails quietly on purpose: it never throws errors into your app and
never slows it down. The downside is that a wrong setup gives you silence
instead of an error. This page covers the usual causes.

## Turn on debug first

Debug logging tells you whether the collector is on, when batches are sent, and
whether sending failed:

```ts theme={null}
const fog = foglamp({ debug: true });
```

If you see `[foglamp] FOGLAMP_API_KEY not set — telemetry disabled (no-op).`,
that is your answer. See the first item below.

## No traces at all

<AccordionGroup>
  <Accordion title="The API key isn't set">
    Without `FOGLAMP_API_KEY` (or an explicit `apiKey`), Foglamp does nothing.
    Set the key in the environment where the code actually runs. The usual
    mistake is a `.env` file that isn't loaded, or a key set locally but not in
    the deployed environment.
  </Accordion>

  <Accordion title="You didn't flush before the process ended">
    Serverless platforms can freeze the process as soon as your handler
    returns, before the data is sent. Await `fog.flush()` before returning. On
    AWS Lambda this is required. See [Runtimes and flushing](/sdk/runtimes).
  </Accordion>

  <Accordion title="The endpoint is wrong">
    The hosted endpoint is the default. If you self-host, set
    `FOGLAMP_INGEST_URL` to your own ingest API, for example
    `http://your-host:4000/ingest`, and make sure it ends with `/ingest`.
    Debug logging shows failed responses from the endpoint.
  </Accordion>

  <Accordion title="The integration isn't attached">
    Per-call tracing only works if the call actually includes the integration
    in its `telemetry.integrations` array. Check that it does, or register
    globally with `registerTelemetry(foglamp())`.
  </Accordion>
</AccordionGroup>

## Traces appear but something's off

<AccordionGroup>
  <Accordion title="Cost shows as a dash, or a model shows as (unknown)">
    Foglamp has no price for that model, so it shows nothing rather than a
    wrong number. Prices come from
    [OpenRouter](https://openrouter.ai/api/v1/models) and refresh every 24
    hours, so this usually fixes itself once the model is listed. Token counts
    and timing are not affected. See [Cost and pricing](/dashboard/cost).
  </Accordion>

  <Accordion title="No prompt or response text on spans">
    Text capture may be off. Check that you haven't set `recordInputs: false`
    or `recordOutputs: false`, and that `maxPayloadChars` isn't cutting off
    more than you expect. See [Configuration](/sdk/configuration).
  </Accordion>

  <Accordion title="New spans are rejected with a 429">
    Your organization has used up its monthly span quota. The dashboard shows a
    red banner when this happens. Upgrade the plan or wait for the period to
    reset. See [Projects, keys and billing](/dashboard/account#usage).
  </Accordion>

  <Accordion title="Streaming replay is missing when using global registration">
    When many streams run at the same time on one globally registered
    collector, Foglamp can't always tell which stream a token belongs to, so it
    drops the sample. Use a per-call `fog.integration(...)` for reliable
    replay.
  </Accordion>

  <Accordion title="Embedding calls have no tokens or cost">
    Embeddings aren't captured yet. `embed` and `embedMany` produce a trace
    with a root span but no usage. See the
    [data model](/concepts/data-model#how-it-streams).
  </Accordion>
</AccordionGroup>

## Still stuck?

Turn on `debug` and send transport errors somewhere you'll see them:

```ts theme={null}
const fog = foglamp({
  debug: true,
  onError: (err) => console.error("[foglamp]", err),
});
```

Foglamp never retries a failed batch. A failed send is reported to `onError`
and dropped, so `onError` is the place to catch transport problems.