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

> How BotGauge tracing works: standard OpenTelemetry over OTLP/HTTP, session and agent identity, privacy defaults, and the two ways to send traces.

BotGauge ingests standard OpenTelemetry traces over OTLP/HTTP at `https://api.botgauge.com/v1/traces`. You can send them in two ways, and both end up at the same endpoint.

| | BotGauge SDK (recommended) | Any OTLP exporter |
| - | - | - |
| What it is | A Python package built on the stock OpenTelemetry SDK | An exporter you already run, pointed at BotGauge |
| Session and agent identity | Added to every span | Not added |
| PII and credential masking | On by default | Not applied |
| Zero-code launch | `botgauge instrument` | Not applicable |
| Framework producers | 11 frameworks, from LangChain to MCP | Whatever instrumentors you install yourself |
| Install | `pip install botgauge` | Nothing to install |

## The model: sessions, turns, and agents

BotGauge organizes spans around three identifiers so you can follow a result back to the conversation and the agent version that produced it.

A **session** is the long-lived conversation or run you pass as `session_id`. A **turn** is one unit of work inside it, opened with `tracing.turn()`. An **agent** is the named agent doing the work, opened with `tracing.agent()`, optionally with a `revision_id` that identifies which version of the agent ran.

Every span created inside those contexts carries four attributes.

| Attribute | Meaning |
| - | - |
| `botgauge.session.id` | The session the turn belongs to |
| `botgauge.turn.id` | The turn the span ran in |
| `botgauge.agent.id` | The agent that did the work |
| `botgauge.agent.revision.id` | The agent revision, when you provide one |

Spans from instrumentation you did not wrap, such as a framework traced by the zero-code launcher in an app that never imports `botgauge`, are still exported, but without session or agent ids.

## What is exported

The SDK exports gzip-compressed OTLP protobuf, and it sends your key only as an `Authorization: Bearer` header. By default it exports prompts, responses, and tool data with detected PII and credentials masked, and it leaves out images, audio, and embedding vectors. You can tighten or loosen this with [capture and redaction](https://www.botgauge.com/docs/tracing/capture-and-redaction.md).

BotGauge's exporter never reads the standard `OTEL_EXPORTER_OTLP_*` variables, so the endpoint and headers of your own collector stay separate and never receive the BotGauge key.

## Requirements

The SDK needs Python 3.10 or newer and depends only on OpenTelemetry. Framework tracing is added through optional extras that you install for the frameworks your app uses.

> [!WARNING]
>
> Early release (0.x). Public API shapes may still change before 1.0. Pin the version in production and read the release notes before upgrading.

Start tracing your agentCreate a project and get your API key on [BotGauge](https://cloud.botgauge.com).

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

## Where to go next

> **[Get your API key](https://www.botgauge.com/docs/tracing/api-key.md)**
>
> Create a project key and put it where BotGauge looks for it.

> **[Install the SDK](https://www.botgauge.com/docs/tracing/install.md)**
>
> Install the package and the extras for your frameworks.

> **[Manual tracing](https://www.botgauge.com/docs/tracing/manual-tracing.md)**
>
> Wrap turns and agents in code with `tracing.init()`.

> **[Zero-code instrumentation](https://www.botgauge.com/docs/tracing/zero-code.md)**
>
> Trace an app you can't or don't want to edit.

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


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