https://github.com/pgx-contrib/pgxtrace

Composite query tracer for pgx v5 — chain multiple tracers (OpenTelemetry, logging, metrics) on a single pgx connection
https://github.com/pgx-contrib/pgxtrace

go golang opentelemetry pgx pgxpool postgresql tracer

Last synced: 29 days ago
JSON representation

Composite query tracer for pgx v5 — chain multiple tracers (OpenTelemetry, logging, metrics) on a single pgx connection

• Host: GitHub
• URL: https://github.com/pgx-contrib/pgxtrace
• Owner: pgx-contrib
• License: mit
• Created: 2024-03-03T10:51:17.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2026-05-10T10:12:40.000Z (about 1 month ago)
• Last Synced: 2026-05-10T12:23:03.221Z (about 1 month ago)
• Topics: go, golang, opentelemetry, pgx, pgxpool, postgresql, tracer
• Language: Go
• Homepage: https://pkg.go.dev/github.com/pgx-contrib/pgxtrace
• Size: 62.5 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# pgxtrace

[![CI](https://github.com/pgx-contrib/pgxtrace/actions/workflows/ci.yml/badge.svg)](https://github.com/pgx-contrib/pgxtrace/actions/workflows/ci.yml)

[![Release](https://img.shields.io/github/v/release/pgx-contrib/pgxtrace?include_prereleases)](https://github.com/pgx-contrib/pgxtrace/releases)

[![Go Reference](https://pkg.go.dev/badge/github.com/pgx-contrib/pgxtrace.svg)](https://pkg.go.dev/github.com/pgx-contrib/pgxtrace)

[![License](https://img.shields.io/github/license/pgx-contrib/pgxtrace)](LICENSE)

[![Go](https://img.shields.io/badge/Go-1.25-00ADD8?logo=go&logoColor=white)](https://go.dev)

[![pgx](https://img.shields.io/badge/pgx-v5-blue)](https://github.com/jackc/pgx)

`CompositeQueryTracer` is a decorator for [pgx v5](https://github.com/jackc/pgx)

that chains multiple tracers together. Assign it to `ConnConfig.Tracer` and

every database operation is dispatched to all registered tracers in order —

query, batch, connect, prepare, and copy-from.

## Installation

```bash

go get github.com/pgx-contrib/pgxtrace

```

## Usage

### Connection pool

```go

config, err := pgxpool.ParseConfig(os.Getenv("PGX_DATABASE_URL"))

if err != nil {

    panic(err)

}

config.ConnConfig.Tracer = pgxtrace.CompositeQueryTracer{

    &myTracer{},

    &anotherTracer{},

}

pool, err := pgxpool.NewWithConfig(context.Background(), config)

if err != nil {

    panic(err)

}

defer pool.Close()

```

### Mixing tracer types

Each element only needs to implement `pgx.QueryTracer`. Elements that also

implement `pgx.ConnectTracer`, `pgx.BatchTracer`, `pgx.PrepareTracer`, or

`pgx.CopyFromTracer` are automatically called for those operations:

```go

config.ConnConfig.Tracer = pgxtrace.CompositeQueryTracer{

    &pgxotel.QueryTracer{Name: "my-service"},  // all five interfaces

    &myAuditLogger{},                           // QueryTracer only

}

```

## Development

### DevContainer

Open in VS Code with the Dev Containers extension. The environment provides Go,

PostgreSQL 18, and Nix automatically.

```

PGX_DATABASE_URL=postgres://vscode@postgres:5432/pgxtrace?sslmode=disable

```

### Nix

```bash

nix develop          # enter shell with Go

go tool ginkgo run -r

```

### Run tests

```bash

# Unit tests only (no database required)

go tool ginkgo run -r

# With integration tests

export PGX_DATABASE_URL="postgres://localhost/pgxtrace?sslmode=disable"

go tool ginkgo run -r

```

## License

[MIT](LICENSE)