Manual tracing

Call tracing.init() once at startup. Wrap each unit of work in tracing.turn() for the session and tracing.agent() for the agent doing the work. Every span opened inside them carries botgauge.session.id, botgauge.turn.id, botgauge.agent.id, and botgauge.agent.revision.id.

quickstart.py

from botgauge import tracing

tracing.init()  # reads BOTGAUGE_API_KEY, and BOTGAUGE_ENDPOINT if set

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()

API summary

Call	What it does
`tracing.init()`	Starts tracing and returns the tracer provider. Call it once at startup.
`tracing.turn(session_id=...)`	Opens a turn for a session. Spans inside carry the session and turn ids.
`tracing.agent(name, revision_id=...)`	Marks the agent doing the work. Spans inside carry the agent id and revision id.
`tracing.get_tracer()`	Returns a tracer for creating your own spans.
`tracing.flush()`	Sends any spans still waiting in the export queue.
`tracing.shutdown()`	Flushes and stops tracing. Call it before your process exits.

init() accepts arguments that override the environment, including api_key, endpoint, headers, capture, redacted, tracer_provider, sample_ratio, and capture_allow_keys. Arguments always win over environment variables, for example tracing.init(api_key=..., endpoint=...).

How init() picks its settings

With no arguments, init() reads BOTGAUGE_API_KEY. With only a key set, it sends to https://api.botgauge.com/v1/traces. Set BOTGAUGE_ENDPOINT to send to a different collector. The key goes out only as Authorization: Bearer <key>, and the body is gzip-compressed OTLP protobuf. If you pass your own Authorization header in headers=, it replaces the key. init() does not read .env files, so load yours first. See Get your API key. It also never reads OTEL_EXPORTER_OTLP_* variables.

With neither a key nor an endpoint, init() prints botgauge: no endpoint configured; BotGauge export disabled. to stderr and sends nothing. For local debugging, set BOTGAUGE_CONSOLE_EXPORT=1 to print spans to stdout instead.

Rejected keys never crash your app

Export runs on a background thread. On the first 401 or 403, the SDK logs one line, botgauge: BotGauge rejected the API key (401 ...), which asks you to check the key. If you passed your own Authorization header in headers=, the line names that header instead, because it replaces the key. If you set an endpoint but no key, the message says no credential was sent. BotGauge reports problems as warnings on the standard Python logger named botgauge, so you can route or silence them like any other logger.

Already using OpenTelemetry

tracing.init() attaches to your existing tracer provider instead of replacing it, so spans from your own instrumentation reach BotGauge too, with the same privacy masking. To attach a framework instrumentor in code, pass the provider that init() returns.

app.py

from botgauge import tracing
from openinference.instrumentation.openai import OpenAIInstrumentor

provider = tracing.init()
OpenAIInstrumentor().instrument(tracer_provider=provider)

Each framework page shows the exact instrumentor to use. See supported frameworks.

Wrap your first turn and agent

Try BotGauge →

Sampling

When BotGauge creates the provider and you don’t pass sample_ratio=, it honors the standard OTEL_TRACES_SAMPLER variables, so a sampler configured for another tool also samples BotGauge’s traces. BotGauge prints a one-time warning at startup when it will drop traces. Pass sample_ratio=1.0 to record everything regardless. See environment variables for the full list.

Send traces

Instrument your code

View and score

Help

API summary

How init() picks its settings

Rejected keys never crash your app

Already using OpenTelemetry

Sampling

​API summary

​How init() picks its settings

​Rejected keys never crash your app

​Already using OpenTelemetry

​Sampling

API summary

How init() picks its settings

Rejected keys never crash your app

Already using OpenTelemetry

Sampling