> ## Documentation Index
> Fetch the complete documentation index at: https://www.botgauge.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing troubleshooting

> Fix common BotGauge tracing problems: rejected API keys, nothing exported, missing session ids, skipped frameworks, dropped spans, and zero-cost traces.

Start with two commands. `botgauge doctor` shows what the current process has turned on, and `botgauge probe` sends one real span and tells you whether ingest accepted it.

```bash terminal theme={null}
botgauge doctor
BOTGAUGE_API_KEY="<your key>" botgauge probe --endpoint https://api.botgauge.com/v1/traces
```

> **The SDK logs: BotGauge rejected the API key (401 ...)**
>
> Export runs on a background thread, so a rejected key never crashes your app. The SDK logs one line on the first `401` or `403`.
>
> Check that you are using a project API key from the console, which starts with `bg_`. Other BotGauge tokens are rejected with `401`, including the session token your browser gets when you sign in. A revoked key is rejected too, because revocation takes effect immediately.
>
> If you passed your own `Authorization` header in `headers=`, the message names that header instead, because it replaces the key. If you set an endpoint but no key, the message says that no credential was sent.

> **Nothing is exported and stderr says: no endpoint configured; BotGauge export disabled.**
>
> `init()` found neither a key nor an endpoint. Set `BOTGAUGE_API_KEY`, which sends to `https://api.botgauge.com/v1/traces` by default, or set `BOTGAUGE_ENDPOINT`. `init()` doesn't read `.env` files, so load yours first. For local debugging, set `BOTGAUGE_CONSOLE_EXPORT=1` to print spans to stdout.

> **The key in my .env file isn't picked up under botgauge instrument**
>
> Your app's own `load_dotenv()` runs too late for the launcher. Pass the file to the launcher with `botgauge instrument --env-file .env python app.py`.

> **Tracing is off and no spans are recorded**
>
> Check whether `OTEL_SDK_DISABLED=true` is set. It turns tracing off entirely, with or without your own provider.

> **Spans arrive without session or agent ids**
>
> Wrap the work in `tracing.turn(session_id=...)` and `tracing.agent(...)`. An app that never imports `botgauge` still has its LLM spans exported under the zero-code launcher, but without ids. Spans sent through a plain OTLP exporter or a Collector never carry them.

> **Some traces are missing, and a warning says traces will be dropped**
>
> A sampler set for another tool is applying. When BotGauge creates the provider and `sample_ratio=` isn't given, it honors `OTEL_TRACES_SAMPLER` and `OTEL_TRACES_SAMPLER_ARG`, and prints a one-time warning when it will drop traces. `botgauge doctor` shows the active sampler. Pass `sample_ratio=1.0` to record everything.

> **A framework is skipped: instrumentor did not instrument: DependencyConflict**
>
> The framework version isn't supported by the instrumentor the extra installs, so BotGauge's producer isn't turned on. For example, the `[google-adk]` extra needs google-adk 2.10 or newer. Upgrade the framework, or see [versions not verified](https://www.botgauge.com/docs/integrations/versions-not-verified.md#instrumentors-that-dont-support-your-version). `--strict` refuses to start in this case.

> **Only part of a Google ADK app is traced, and the log says failed to activate instrumentor 'google\_adk'**
>
> Instrumentor 0.1.28 raises `AttributeError` on google-adk 2.10.0. Use the `[google-adk]` extra, which installs instrumentor 1.0.4, and don't pin 0.1.28 with ADK 2.10.

> **Startup says a framework is traced at a version BotGauge has not verified**
>
> This is a warning, not an error. The framework is traced anyway. To trace only verified versions, set `BOTGAUGE_VERIFIED_ONLY=1`. To fail your CI run instead, use `botgauge instrument --strict`.

> **Framework calls aren't traced, only my own spans**
>
> Only the `botgauge` package is installed, without the framework extra. Startup names the extra to install, for example `pip install "botgauge[langchain]"`. Run `botgauge setup --detect` to see recommendations.

> **PydanticAI traces show zero cost**
>
> PydanticAI reads token counts through `genai-prices`, and every PydanticAI before 2.17 records none with `genai-prices` 0.1.0 or newer. Upgrade to PydanticAI 2.17 or newer, or pin `genai-prices==0.0.73` with the other pins listed on the [PydanticAI page](https://www.botgauge.com/docs/integrations/pydantic-ai.md).

> **Sending to a remote http\:// endpoint fails**
>
> BotGauge doesn't send the key to a remote `http://` endpoint by default. Use `https`. If you must use `http`, set `BOTGAUGE_ALLOW_INSECURE_HTTP=true`. Local addresses such as `127.0.0.1` need no opt-in.

> **My PII is exported unmasked**
>
> Check for `redacted=False` or `BOTGAUGE_REDACTED=false`. That setting overrides the capture mode, so every mode then exports the original content. Spans sent through a plain OTLP exporter or Collector are never masked. Masking also catches common formats only, so use `metadata` capture for data you must never export. See [Capture and redaction](https://www.botgauge.com/docs/tracing/capture-and-redaction.md).

Check your setup in the consoleSign in to [BotGauge](https://cloud.botgauge.com) to confirm your traces arrive in Logs after you fix the issue.

[Try BotGauge →](https://cloud.botgauge.com)

> **botgauge probe exits 1**
>
> It printed `probe: ingest acceptance not confirmed`, which means the span was rejected or timed out. Check the key and the endpoint, and check that your network allows outbound HTTPS to `api.botgauge.com`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.