What is pgtrace?

pgtrace, published as pg_otel_tracer, is a PostgreSQL extension written in Rust that plugs into the database's internal query hooks so every SQL statement can be tracked as part of a larger distributed trace. OpenTelemetry, or OTEL, is an open standard for recording and passing traces across service boundaries. pgtrace bridges the gap between your application's existing trace and what happens inside PostgreSQL itself. Here is how it works: your application embeds a W3C traceparent identifier inside a SQL comment when it sends a query to PostgreSQL. The extension reads that identifier and creates timed spans covering each phase of the query's life, including the planning phase, the execution start, and the data retrieval phase. These spans are collected in a shared memory ring buffer and exported asynchronously by a background worker process every 500 milliseconds via OTLP over HTTP. You can then view the full end to end trace in tools like Jaeger or Tempo, seeing how long PostgreSQL spent on each query alongside your application's other service calls. The extension is designed to be safe for production. It drops spans rather than blocking the database if the export queue fills up, supports an adjustable sampling rate so you can trace a fraction of queries rather than all of them, and provides a live switch SQL function to disable tracing without a database restart. A status function reports the current version, whether tracing is enabled, the sampling rate, and how many spans are queued or dropped. Installation requires preloading the extension via postgresql.conf and running a single CREATE EXTENSION command, or you can try it quickly with the included Docker setup that starts Postgres, an OTEL Collector, Jaeger, and a Go demo application together. The project is licensed under Apache-2.0.