fastotel

A Rust-backed drop-in for the OpenTelemetry Python SDK that takes tracing overhead off the request path.

Status: pre-alpha. OTLPSpanProcessor sends every field of a span over OTLP/HTTP, encoded as OTLPSpanExporter encodes it, configured as it is configured, compressed, through TLS and with its retries, and batches as BatchSpanProcessor does, but a process forked after the first span exports nothing from the child yet. The road to 1.0 is in #5.

Why

Instrumentation packages (FastAPI, httpx, SQLAlchemy, aiokafka, …) depend only on opentelemetry-api. fastotel replaces parts of opentelemetry-sdk behind that API, so existing instrumentation keeps working.

In the pure-Python SDK, the BatchSpanProcessor worker thread encodes OTLP protobuf, gzips and sends spans while holding the GIL, so it competes for CPU with request handling. In Rust, batching, encoding, compression and export run on a thread that never takes the GIL.

Installation

pip install fastotel

Wheels are built for Linux (glibc and musl), macOS and Windows, x86_64 and arm64:

CPython 3.10 reached end of life on 2026-10-01 and is not supported. Free-threaded 3.13t is not supported either: it was experimental, and PyO3 builds free-threaded extensions from 3.14 on.

Usage

fastotel replaces BatchSpanProcessor with OTLPSpanExporter; the SDK keeps creating spans:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from fastotel import OTLPSpanProcessor

provider = TracerProvider()
provider.add_span_processor(OTLPSpanProcessor())  # reads OTEL_EXPORTER_OTLP_* and OTEL_BSP_*
trace.set_tracer_provider(provider)

on_end copies the span into Rust and returns; a native thread, started by the first span, batches, encodes and sends spans without taking the GIL. As with BatchSpanProcessor, only sampled spans are exported. The requests decode to what OTLPSpanExporter sends for the same spans; where they differ is in ADR 0003.

Exporter

The arguments and variables of OTLPSpanExporter (opentelemetry-exporter-otlp-proto-http), with its defaults, precedence and parsing: an argument overrides the OTEL_EXPORTER_OTLP_TRACES_* variable, which overrides the OTEL_EXPORTER_OTLP_* one; an empty variable counts as unset. A timeout or a compression that does not parse gives the default, and a header entry that does not parse is skipped, each with the reference's warning on the fastotel logger.

OTLPSpanExporter's session, max_request_size and meter_provider, and its credential provider variables, have no counterpart. Where fastotel differs from the reference (its own user agent, a header that HTTP cannot carry raises ValueError, compression also takes a string) is in ADR 0005.

Delivery

As the OTLP/HTTP specification asks and OTLPSpanExporter does: a batch answered with 429, 502, 503 or 504, or that meets a connection error (refused, dropped, DNS, TLS), is sent again after 1, 2, 4, 8, 16 s, give or take 20%, or after the answer's Retry-After, in at most 6 attempts and only while timeout lasts; any other error drops the batch, and a redirect is not followed and counts as sent. The spans of a dropped batch and those a collector rejects in a partial success are counted (the counts are public with #14). Connections are reused across exports. While the collector is down, a batch costs at most timeout, mostly asleep, and the queue keeps memory bounded; exports resume with the next batch once it is back.

An https:// endpoint is verified through rustls against the OS trust store, so corporate CAs work, or against certificate_file; a TLS file that cannot be read or holds no usable certificate or key raises from the constructor. Where this differs from the reference (gzip at level 6, TLS files checked at construction, among others) is in ADR 0006.

Batching

The arguments and variables of BatchSpanProcessor, with its defaults, parsing and checks: an argument overrides its variable, a variable that is not an integer gives the default and an error log on the fastotel logger, and a value out of range raises ValueError from the constructor.

Where this differs from BatchSpanProcessor (a full queue drops the newest span rather than the oldest, among others) is in ADR 0004.

Development

Needs uv and a Rust toolchain (rustup).

make install   # build the extension, install the dev dependencies
make test      # run the tests, those of the Rust export pipeline (crates/export) too
make lint      # ruff, mypy, cargo fmt, clippy
make bench     # what the stock SDK costs an application, on a GIL and a free-threaded build (~30 min)

Every change that reaches master is a release: a pull request bumps the version in pyproject.toml (uv version --bump patch) and adds its section to CHANGELOG.md.

License

MIT