Tracing quickstart

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.

Create a project API key

Sign in at 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 for details.

Set the key in your environment

terminal

export BOTGAUGE_API_KEY="bg_..."

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

Install the SDK

terminal

pip install botgauge

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

terminal

botgauge setup --install

Trace a unit of work

quickstart.py

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.

Confirm ingest accepted the trace

terminal

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.

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.

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.

terminal

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 live

Try BotGauge →

Next steps

Instrument your framework

Copy-paste setup for 11 frameworks, in code and zero-code.

Control what leaves your app

Choose what content is exported and how PII and credentials are masked.

Debug a missing trace

Fixes for rejected keys, skipped frameworks, and dropped spans.

View your logs

Sessions, traces, spans, and evaluation scores in the console.

Set up your team

Workspaces, projects, roles, and invitations.

Send traces

Instrument your code

View and score

Help

Trace a real framework without editing code

Next steps

Instrument your framework

Control what leaves your app

Debug a missing trace

View your logs

Set up your team

​Trace a real framework without editing code

​Next steps

Instrument your framework

Control what leaves your app

Debug a missing trace

View your logs

Set up your team

Trace a real framework without editing code

Next steps