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

# Manual tracing

> Use tracing.init(), tracing.turn(), and tracing.agent() to add BotGauge session and agent identity to every span, and learn how init() reads its settings.

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

```python quickstart.py theme={null}
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](https://www.botgauge.com/docs/tracing/api-key.md#using-a-env-file). It also never reads `OTEL_EXPORTER_OTLP_*` variables.

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

```python app.py theme={null}
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](https://www.botgauge.com/docs/integrations/overview.md).

Wrap your first turn and agentSign in to [BotGauge](https://cloud.botgauge.com) to create a key, then add tracing.init() to your app.

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

## 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](https://www.botgauge.com/docs/reference/environment-variables.md) for the full list.


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