Skip to main content

FastAPI traces with OpenTelemetry, shown as a waterfall

Install the OpenTelemetry Python distro, set OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:8000 and OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf, and start your FastAPI app with opentelemetry-instrument. Each request then shows up in Buggregator as a trace, with its spans on a waterfall. Your app code does not change.

Steps

1. Start Buggregator

OTLP comes in on the main HTTP port, 8000.

bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/buggregator/server:latest

2. Install the OpenTelemetry packages

opentelemetry-bootstrap adds the instrumentation for the libraries it finds, FastAPI among them.

bash
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

3. Set the standard variables

OTEL_EXPORTER_OTLP_PROTOCOL must be http/protobuf or http/json: Buggregator does not accept gRPC. It does not take metrics either, so turn the metrics exporter off.

dotenv
OTEL_SERVICE_NAME=checkout
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:8000
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none

In Docker Compose, replace 127.0.0.1 with the Buggregator service name, for example buggregator.

4. Start the app under opentelemetry-instrument

bash
opentelemetry-instrument uvicorn main:app

5. Open the trace

Call an endpoint, then open http://127.0.0.1:8000 and the Sentry page, Traces tab. The trace is labeled OTel and shows your service name. Open it to see each span on a timeline, with a Service column. A span with status ERROR is marked as an error.

Why it works

opentelemetry-instrument sets up the OTel SDK and the FastAPI instrumentation before your app starts. The OTLP exporter adds /v1/traces to the endpoint and posts each batch of spans there. Buggregator answers that path on port 8000 and shows the spans next to traces from Sentry SDKs. OTEL_SERVICE_NAME is what the UI shows as the service.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you