Skip to main content
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.
terminal
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.
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.
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.
Check whether OTEL_SDK_DISABLED=true is set. It turns tracing off entirely, with or without your own provider.
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.
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.
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. --strict refuses to start in this case.
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.
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.
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 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.
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.
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.

Check your setup in the console

Sign in to BotGauge to confirm your traces arrive in Logs after you fix the issue.

Try BotGauge →
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.