pg_tracing

Overview

Version

Build

You can build the RPM / DEB packages for pg_tracing using pig build:

pig build pkg pg_tracing         # build RPM / DEB packages

Install

You can install pg_tracing directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

• Install
• pig
• dnf
• apt

pig install pg_tracing;          # Install for current active PG version

pig ext install -y pg_tracing -v 18  # PG 18
pig ext install -y pg_tracing -v 17  # PG 17
pig ext install -y pg_tracing -v 16  # PG 16
pig ext install -y pg_tracing -v 15  # PG 15
pig ext install -y pg_tracing -v 14  # PG 14

dnf install -y pg_tracing_18       # PG 18
dnf install -y pg_tracing_17       # PG 17
dnf install -y pg_tracing_16       # PG 16
dnf install -y pg_tracing_15       # PG 15
dnf install -y pg_tracing_14       # PG 14

apt install -y postgresql-18-pg-tracing   # PG 18
apt install -y postgresql-17-pg-tracing   # PG 17
apt install -y postgresql-16-pg-tracing   # PG 16
apt install -y postgresql-15-pg-tracing   # PG 15
apt install -y postgresql-14-pg-tracing   # PG 14

Preload:

shared_preload_libraries = 'pg_tracing';

Create Extension:

CREATE EXTENSION pg_tracing;

Usage

pg_tracing: distributed tracing for PostgreSQL

pg_tracing generates server-side spans for distributed tracing. It creates spans for planner, executor, plan nodes, nested queries, triggers, parallel workers, and transaction commits.

Trace Propagation via SQLCommenter

Pass trace context as a SQL comment. Queries with a sampled flag will generate spans:

/*traceparent='00-00000000000000000000000000000123-0000000000000123-01'*/ SELECT 1;

Trace Propagation via GUC

BEGIN;
SET LOCAL pg_tracing.trace_context='traceparent=''00-00000000000000000000000000000005-0000000000000005-01''';
UPDATE pgbench_accounts SET abalance=1 WHERE aid=1;
COMMIT;

Standalone Sampling

Randomly sample queries without external trace context:

SET pg_tracing.sample_rate = 1.0;  -- trace all queries
SELECT 1;

Viewing Spans

-- Consume spans (removes them from buffer)
SELECT trace_id, parent_id, span_id, span_start, span_end, span_type, span_operation
FROM pg_tracing_consume_spans ORDER BY span_start;

-- Peek at spans (non-destructive)
SELECT * FROM pg_tracing_peek_spans;

-- Export as OTLP JSON
SELECT pg_tracing_json_spans();

Statistics

SELECT * FROM pg_tracing_info;
SELECT pg_tracing_reset();

Sending Spans to OpenTelemetry Collector

Configure in postgresql.conf:

pg_tracing.otel_endpoint = http://127.0.0.1:4318/v1/traces
pg_tracing.otel_naptime = 2000

Key GUC Parameters