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:

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

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.

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.

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.

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()).

Traces appear but something’s off

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

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.

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.

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.

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.

Still stuck?

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

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.