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

# Zero-code instrumentation

> Trace a Python AI agent without editing it. Launch your app with botgauge instrument, load a .env file, and gate CI on verified framework versions.

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](https://www.botgauge.com/docs/integrations/versions-not-verified.md).

```bash terminal theme={null}
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.

> [!NOTE]
>
> 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 (...)`.

```bash terminal theme={null}
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 commandGet your API key from [BotGauge](https://cloud.botgauge.com) and run botgauge instrument to start tracing.

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

## Next steps

Pick your framework on the [supported frameworks](https://www.botgauge.com/docs/integrations/overview.md) page for a tested zero-code sample, or tune what leaves your app with [capture and redaction](https://www.botgauge.com/docs/tracing/capture-and-redaction.md).


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