BotGauge Python SDK

Trace AI agents in production, safely and privately, without slowing your application down.
Built on OpenTelemetry.

BotGauge records what your agents do: every turn of a conversation, the agents involved, their LLM calls with model and token counts, and their tool calls. You see it in the BotGauge console as sessions you can search and inspect.

• Two ways in. Add three lines to your code, or trace an existing app without changing it: botgauge instrument python app.py.
• Private by default. Detected PII and credentials (emails, card numbers, API keys, passwords) are masked before anything leaves your process. Images, audio and embeddings stay out unless you ask for them.
• Never in your way. Export runs on a background thread with bounded queues and timeouts. A slow or unreachable endpoint never blocks or crashes your app.
• Standard OpenTelemetry. It works alongside your existing OpenTelemetry setup and carries W3C trace context across services.

Install

pip install botgauge          # the tracing SDK (Python library) and the `botgauge` command
botgauge setup --install      # adds tracing for the frameworks your app uses

What pip install botgauge gives you: the tracing SDK (from botgauge import tracing) and the botgauge command. On its own it records the turns, agents and spans your code creates. It does not install tracing for every framework BotGauge supports; you add only what your app uses:

• botgauge setup --install finds the frameworks installed in your environment (without importing them) and installs the matching BotGauge extra for each, such as botgauge[langchain], at your installed BotGauge version. botgauge setup --detect lists them without installing anything.
• Or name the extra yourself, for example in requirements.txt: botgauge[langchain]. The extras are listed under Frameworks.

An extra adds the instrumentation that records your framework's LLM calls (model, prompts, token counts) and tool calls.

No botgauge command installs anything except setup --install: botgauge instrument uses what is installed and, when your app imports a framework without its tracing, logs which extra to add.

Get an API key

Sign in at cloud.botgauge.com and create an API key. It starts with bg_. Then make it available to your app:

export BOTGAUGE_API_KEY="bg_..."

Quickstart

Zero-code: trace an existing app as it is. botgauge instrument turns on the tracing your extras installed.

botgauge instrument python app.py

In code: start tracing, attach your framework's instrumentor, and wrap each turn of a conversation.

from botgauge import tracing
from openinference.instrumentation.langchain import LangChainInstrumentor

provider = tracing.init()                            # reads BOTGAUGE_API_KEY
LangChainInstrumentor().instrument(tracer_provider=provider)

with tracing.turn(session_id="ses_123"), tracing.agent("support-agent"):
    ...                                              # your agent's LLM and tool calls

tracing.shutdown()                                   # flushes on exit

botgauge doctor checks your setup: installed instrumentation, trace propagation and configuration.

Frameworks

In code, import the instrumentor from openinference.instrumentation.<framework> (for example from openinference.instrumentation.openai import OpenAIInstrumentor) and call .instrument(tracer_provider=provider) on it after provider = tracing.init(), as in the quickstart. PydanticAI instruments itself instead:

from botgauge import tracing
from openinference.instrumentation.pydantic_ai import OpenInferenceSpanProcessor
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings

provider = tracing.init()
# version=5 for PydanticAI 2; use version=3 on PydanticAI 1.x
Agent.instrument_all(InstrumentationSettings(tracer_provider=provider, version=5))
provider.add_span_processor(OpenInferenceSpanProcessor())

Zero-code needs none of this: botgauge instrument does it for every installed extra.

BotGauge verifies exact framework and instrumentor versions in CI. Other versions are traced too, and startup says when a version isn't one BotGauge has verified, and why.

Already instrumented, or a framework not listed?

• You already have the instrumentor installed: pip install botgauge is enough. botgauge instrument finds installed instrumentors whichever way they were installed, and traces a version BotGauge hasn't verified too, saying so at startup. 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.
• You already use OpenTelemetry: tracing.init() attaches to your existing tracer provider instead of replacing it, so spans from your instrumentation are exported to BotGauge too, with the same privacy masking.
• Your framework is not in the table: zero-code doesn't trace it, but in code you can. Install its OpenInference instrumentor, or any instrumentor that follows the OpenTelemetry GenAI conventions, and call .instrument(tracer_provider=provider) after provider = tracing.init(). BotGauge exports those LLM and tool spans with the same privacy masking; they just aren't versions BotGauge has verified.
• Your framework calls the OpenAI or Anthropic SDK underneath: botgauge[openai] or botgauge[anthropic] traces those LLM calls, zero-code included, without the framework's own steps.
• Anything else you can trace yourself with tracing.turn(), tracing.agent() and tracing.get_tracer().

Privacy controls

OTEL_SDK_DISABLED=true turns tracing off without code changes.

Packages

All three release together with the same version. Python 3.10 or later.

Links

• Website: botgauge.com
• Console and API keys: cloud.botgauge.com
• Support: support@botgauge.com

License

Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2). You may use, modify and redistribute the software for any purpose other than a competing commercial product or service. Each release becomes available under the Apache License 2.0 two years after it is published.