Zero-code instrumentation

To trace an app without editing it, launch it through the botgauge command. The launcher reads its settings from the environment, starts tracing, and turns on the producer for each installed framework whose extra is installed. Versions BotGauge hasn’t verified are traced too. See versions not verified.

terminal

export BOTGAUGE_API_KEY="<your BotGauge API key>"
# optional: BOTGAUGE_ENDPOINT defaults to https://api.botgauge.com/v1/traces

botgauge instrument python your_app.py

# or read the key from a .env file (variables already set win; the flag can repeat)
botgauge instrument --env-file .env python your_app.py

You don’t need init() under the launcher.

What gets exported

What you see depends on what is installed in the environment.

What’s installed	What `botgauge instrument` exports
The `botgauge` package only, no extras	Spans you create with the BotGauge API (`turn()`, `agent()`, `get_tracer()`). Framework calls are not traced, and startup names the extra to install, for example `pip install "botgauge[langchain]"`.
Package, framework extra, and a verified version	The above, plus the framework’s own spans, such as LangGraph graph, node, and LLM spans, from an unmodified app.
Package, framework extra, and any other version	Traced as well. Startup logs `botgauge: tracing <framework> at a version BotGauge has not verified: ...` with the reason. `BOTGAUGE_VERIFIED_ONLY=1` skips those versions instead.
Package, framework extra, but the instrumentor doesn’t support your framework version	BotGauge’s producer isn’t turned on, and it says so. Startup logs the framework as skipped with `instrumentor did not instrument: DependencyConflict: ...`, and `--strict` refuses to start. For example, the `[google-adk]` extra needs google-adk 2.10 or newer, and older ADK still sends its own built-in spans.

An app that never imports botgauge still gets its LLM spans exported, but without session or agent ids. To group spans by session, wrap the work in tracing.turn() and tracing.agent() as the framework samples do.

Loading a .env file

--env-file handles comments, export prefixes, and quotes. Variables already set in the environment win over the file, and the flag can be repeated. Your app sees the file’s other variables too. An unreadable file stops the launcher before your app starts.

Your app’s own load_dotenv() runs too late for the launcher. Always use --env-file for zero-code runs, and keep the .env file out of version control.

Use `--strict` as a CI gate

botgauge instrument --strict refuses to start your app when BotGauge would trace a framework at a version that isn’t verified, or when instrumentation problems occur. It exits 1 with a message like botgauge: --strict: not starting the application: version not verified: openai (...).

terminal

botgauge instrument --strict python your_app.py

Setting BOTGAUGE_STRICT=1 has the same effect. Frameworks you trace yourself, declared with BOTGAUGE_PRODUCER_OWNER=<framework>=customer, aren’t checked.

Keeping your own instrumentation

BotGauge’s exporter reads only BOTGAUGE_API_KEY and BOTGAUGE_ENDPOINT. It never uses OTEL_EXPORTER_OTLP_*, so your own collector’s endpoint and headers stay separate and never receive the BotGauge key. If your app already calls .instrument() itself, BotGauge leaves it alone instead of instrumenting twice. Set BOTGAUGE_PRODUCER_OWNER=<framework>=customer to make that explicit.

Launch your app with one command

Get your API key from BotGauge and run botgauge instrument to start tracing.

Try BotGauge →

Next steps

Pick your framework on the supported frameworks page for a tested zero-code sample, or tune what leaves your app with capture and redaction.

Send traces

Instrument your code

View and score

Help

Zero-code instrumentation

What gets exported

Loading a .env file

Use `--strict` as a CI gate

Keeping your own instrumentation

Next steps

​What gets exported

​Loading a .env file

​Use --strict as a CI gate

​Keeping your own instrumentation

​Next steps

What gets exported

Loading a .env file

Use `--strict` as a CI gate

Keeping your own instrumentation

Next steps