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

> Send your first AI agent trace to BotGauge in five minutes: create a project API key, install the Python SDK, and verify ingest with one command.

This guide takes a Python agent from nothing to a trace visible in your BotGauge project. You need Python 3.10 or newer and a BotGauge workspace.

**1. Create a project API key**

Sign in at [cloud.botgauge.com](https://cloud.botgauge.com), finish onboarding for your workspace, then open **Settings, Project, API keys** and choose **Create key**. Copy the key right away. It starts with `bg_` and is shown only once.

Creating keys requires the workspace Admin role. See [API keys](https://www.botgauge.com/docs/platform/api-keys.md) for details.

**2. Set the key in your environment**

```bash terminal theme={null}
export BOTGAUGE_API_KEY="bg_..."
```

The SDK reads `BOTGAUGE_API_KEY` and sends traces to `https://api.botgauge.com/v1/traces` by default.

**3. Install the SDK**

```bash terminal theme={null}
pip install botgauge
```

To also install tracing for the frameworks already in your environment:

```bash terminal theme={null}
botgauge setup --install
```

**4. Trace a unit of work**

```python quickstart.py theme={null}
from botgauge import tracing

tracing.init()  # reads BOTGAUGE_API_KEY

with tracing.turn(session_id="ses_123"):
    with tracing.agent("billing-agent", revision_id="rev_1"):
        tracer = tracing.get_tracer()
        with tracer.start_as_current_span("check_balance"):
            pass  # your own work

tracing.flush()
tracing.shutdown()
```

Run it with `python quickstart.py`.

**5. Confirm ingest accepted the trace**

```bash terminal theme={null}
botgauge probe --endpoint https://api.botgauge.com/v1/traces
```

When the key is valid and ingest accepts the diagnostic span, the command prints `probe: OTLP ingest accepted the diagnostic span.` and exits 0. Any other result exits 1.

**6. See your trace in Logs**

Open **Observability, Logs** in the console and choose the **Sessions** tab. Your run appears with the session ID and agent name from your code, for example `ses_123` and `billing-agent`. Click a row to open it. See [Logs](https://www.botgauge.com/docs/observability/logs.md).

## Trace a real framework without editing code

If your agent already uses a supported framework, you can skip the manual spans and launch it through the BotGauge command instead.

```bash terminal theme={null}
pip install "botgauge[openai]" openai
export OPENAI_API_KEY="..."
botgauge instrument python your_app.py
```

The launcher turns on tracing for every installed framework extra and exports LLM and tool spans with model names, token counts, and timing. To group those spans by session and agent, wrap the work in `tracing.turn()` and `tracing.agent()` as shown above.

Get your API key and go liveSign in to [BotGauge](https://cloud.botgauge.com) to create a project, generate a key, and see your first trace in Logs.

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

## Next steps

> **[Instrument your framework](https://www.botgauge.com/docs/integrations/overview.md)**
>
> Copy-paste setup for 11 frameworks, in code and zero-code.

> **[Control what leaves your app](https://www.botgauge.com/docs/tracing/capture-and-redaction.md)**
>
> Choose what content is exported and how PII and credentials are masked.

> **[Debug a missing trace](https://www.botgauge.com/docs/tracing/troubleshooting.md)**
>
> Fixes for rejected keys, skipped frameworks, and dropped spans.

> **[View your logs](https://www.botgauge.com/docs/observability/logs.md)**
>
> Sessions, traces, spans, and evaluation scores in the console.

> **[Set up your team](https://www.botgauge.com/docs/platform/concepts.md)**
>
> Workspaces, projects, roles, and invitations.


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