otelpgx

package module
v0.9.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 10, 2025 License: Apache-2.0 Imports: 17 Imported by: 80

README

Go Reference

otelpgx

Provides OpenTelemetry instrumentation for the jackc/pgx library.

Requirements

  • go 1.22 (or higher)
  • pgx v5 (or higher)

Usage

Make sure you have a suitable pgx version:

go get github.com/jackc/pgx/v5

Install the library:

go get github.com/exaring/otelpgx

Create the tracer as part of your connection:

cfg, err := pgxpool.ParseConfig(connString)
if err != nil {
    return nil, fmt.Errorf("create connection pool: %w", err)
}

cfg.ConnConfig.Tracer = otelpgx.NewTracer()

conn, err := pgxpool.NewWithConfig(ctx, cfg)
if err != nil {
    return nil, fmt.Errorf("connect to database: %w", err)
}

if err := otelpgx.RecordStats(conn); err != nil {
    return nil, fmt.Errorf("unable to record database stats: %w", err)
}

See options.go for the full list of options.

Documentation

Index

Constants

View Source 
const (
	// RowsAffectedKey represents the number of rows affected.
	RowsAffectedKey = attribute.Key("pgx.rows_affected")
	// QueryParametersKey represents the query parameters.
	QueryParametersKey = attribute.Key("pgx.query.parameters")
	// PrepareStmtNameKey represents the prepared statement name.
	PrepareStmtNameKey = attribute.Key("pgx.prepare_stmt.name")
	// SQLStateKey represents PostgreSQL error code,
	// see https://www.postgresql.org/docs/current/errcodes-appendix.html.
	SQLStateKey = attribute.Key("pgx.sql_state")
	// PGXOperationTypeKey represents the pgx tracer operation type
	PGXOperationTypeKey = attribute.Key("pgx.operation.type")
	// DBClientOperationErrorsKey represents the count of operation errors
	DBClientOperationErrorsKey = attribute.Key("db.client.operation.errors")
)

Variables

This section is empty.

Functions

func RecordStats added in v0.8.0 

func RecordStats(db PoolStats, opts ...StatsOption) error

RecordStats records database statistics for provided pgxpool.Pool at a default 1 second interval unless otherwise specified by the WithMinimumReadDBStatsInterval StatsOption.

Types

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option specifies instrumentation configuration options.

func WithAttributes deprecated 

func WithAttributes(attrs ...attribute.KeyValue) Option

Deprecated: Use WithTracerAttributes.

WithAttributes specifies additional attributes to be added to spans. This is exactly equivalent to using WithTracerAttributes.

func WithDisableConnectionDetailsInAttributes added in v0.9.0 

func WithDisableConnectionDetailsInAttributes() Option

WithDisableConnectionDetailsInAttributes will disable logging the connection details. in the span's attributes.

func WithDisableQuerySpanNamePrefix added in v0.6.0 

func WithDisableQuerySpanNamePrefix() Option

WithDisableQuerySpanNamePrefix will disable the default prefix for the span name. By default, the span name is prefixed with "batch query" or "query".

func WithDisableSQLStatementInAttributes added in v0.4.0 

func WithDisableSQLStatementInAttributes() Option

WithDisableSQLStatementInAttributes will disable logging the SQL statement in the span's attributes.

func WithIncludeQueryParameters added in v0.4.0 

func WithIncludeQueryParameters() Option

WithIncludeQueryParameters includes the SQL query parameters in the span attribute with key pgx.query.parameters. This is implicitly disabled if WithDisableSQLStatementInAttributes is used.

func WithMeterAttributes added in v0.8.0 

func WithMeterAttributes(attrs ...attribute.KeyValue) Option

WithMeterAttributes specifies additional attributes to be added to metrics.

func WithMeterProvider added in v0.8.0 

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider specifies a meter provider to use for creating a meter. If none is specified, the global provider is used.

func WithSpanNameFunc added in v0.5.0 

func WithSpanNameFunc(fn SpanNameFunc) Option

WithSpanNameFunc will use the provided function to generate the span name for a SQL statement. The function will be called with the SQL statement as a parameter.

By default, the whole SQL statement is used as a span name, where applicable.

func WithTracerAttributes added in v0.8.0 

func WithTracerAttributes(attrs ...attribute.KeyValue) Option

WithTracerAttributes specifies additional attributes to be added to spans.

func WithTracerProvider 

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider specifies a tracer provider to use for creating a tracer. If none is specified, the global provider is used.

func WithTrimSQLInSpanName 

func WithTrimSQLInSpanName() Option

WithTrimSQLInSpanName will use the SQL statement's first word as the span name. By default, the whole SQL statement is used as a span name, where applicable.

type PoolStats added in v0.9.2 

type PoolStats interface {
	Stat() *pgxpool.Stat
	Config() *pgxpool.Config
}

PoolStats is an interface that provides access to the pgxpool.Pool's statistics.

type SpanNameFunc added in v0.5.0 

type SpanNameFunc func(stmt string) string

SpanNameFunc is a function that can be used to generate a span name for a SQL. The function will be called with the SQL statement as a parameter.

type StatsOption added in v0.8.0 

type StatsOption interface {
	// contains filtered or unexported methods
}

StatsOption allows for managing RecordStats configuration using functional options.

func WithMinimumReadDBStatsInterval added in v0.8.0 

func WithMinimumReadDBStatsInterval(interval time.Duration) StatsOption

WithMinimumReadDBStatsInterval sets the minimum interval between calls to db.Stats(). Negative values are ignored.

func WithStatsAttributes added in v0.8.0 

func WithStatsAttributes(attrs ...attribute.KeyValue) StatsOption

WithStatsAttributes specifies additional attributes to be added to pgx stat metrics.

func WithStatsMeterProvider added in v0.8.0 

func WithStatsMeterProvider(provider metric.MeterProvider) StatsOption

WithStatsMeterProvider sets meter provider to use for pgx stat metric collection.

type Tracer 

type Tracer struct {
	// contains filtered or unexported fields
}

Tracer is a wrapper around the pgx tracer interfaces which instrument queries with both tracing and metrics. Use NewTracer to create a new instance.

func NewTracer 

func NewTracer(opts ...Option) *Tracer

NewTracer returns a new Tracer.

func (*Tracer) TraceAcquireEnd added in v0.7.0 

func (t *Tracer) TraceAcquireEnd(ctx context.Context, _ *pgxpool.Pool, data pgxpool.TraceAcquireEndData)

TraceAcquireEnd is called when a connection has been acquired.

func (*Tracer) TraceAcquireStart added in v0.7.0 

func (t *Tracer) TraceAcquireStart(ctx context.Context, pool *pgxpool.Pool, data pgxpool.TraceAcquireStartData) context.Context

TraceAcquireStart is called at the beginning of Acquire. The returned context is used for the rest of the call and will be passed to the TraceAcquireEnd.

func (*Tracer) TraceBatchEnd 

func (t *Tracer) TraceBatchEnd(ctx context.Context, _ *pgx.Conn, data pgx.TraceBatchEndData)

TraceBatchEnd is called at the end of SendBatch calls.

func (*Tracer) TraceBatchQuery 

func (t *Tracer) TraceBatchQuery(ctx context.Context, conn *pgx.Conn, data pgx.TraceBatchQueryData)

TraceBatchQuery is called at the after each query in a batch.

func (*Tracer) TraceBatchStart 

func (t *Tracer) TraceBatchStart(ctx context.Context, conn *pgx.Conn, data pgx.TraceBatchStartData) context.Context

TraceBatchStart is called at the beginning of SendBatch calls. The returned context is used for the rest of the call and will be passed to TraceBatchQuery and TraceBatchEnd.

func (*Tracer) TraceConnectEnd 

func (t *Tracer) TraceConnectEnd(ctx context.Context, data pgx.TraceConnectEndData)

TraceConnectEnd is called at the end of Connect and ConnectConfig calls.

func (*Tracer) TraceConnectStart 

func (t *Tracer) TraceConnectStart(ctx context.Context, data pgx.TraceConnectStartData) context.Context

TraceConnectStart is called at the beginning of Connect and ConnectConfig calls. The returned context is used for the rest of the call and will be passed to TraceConnectEnd.

func (*Tracer) TraceCopyFromEnd 

func (t *Tracer) TraceCopyFromEnd(ctx context.Context, _ *pgx.Conn, data pgx.TraceCopyFromEndData)

TraceCopyFromEnd is called at the end of CopyFrom calls.

func (*Tracer) TraceCopyFromStart 

func (t *Tracer) TraceCopyFromStart(ctx context.Context, conn *pgx.Conn, data pgx.TraceCopyFromStartData) context.Context

TraceCopyFromStart is called at the beginning of CopyFrom calls. The returned context is used for the rest of the call and will be passed to TraceCopyFromEnd.

func (*Tracer) TracePrepareEnd 

func (t *Tracer) TracePrepareEnd(ctx context.Context, _ *pgx.Conn, data pgx.TracePrepareEndData)

TracePrepareEnd is called at the end of Prepare calls.

func (*Tracer) TracePrepareStart 

func (t *Tracer) TracePrepareStart(ctx context.Context, conn *pgx.Conn, data pgx.TracePrepareStartData) context.Context

TracePrepareStart is called at the beginning of Prepare calls. The returned context is used for the rest of the call and will be passed to TracePrepareEnd.

func (*Tracer) TraceQueryEnd 

func (t *Tracer) TraceQueryEnd(ctx context.Context, _ *pgx.Conn, data pgx.TraceQueryEndData)

TraceQueryEnd is called at the end of Query, QueryRow, and Exec calls.

func (*Tracer) TraceQueryStart 

func (t *Tracer) TraceQueryStart(ctx context.Context, conn *pgx.Conn, data pgx.TraceQueryStartData) context.Context

TraceQueryStart is called at the beginning of Query, QueryRow, and Exec calls. The returned context is used for the rest of the call and will be passed to TraceQueryEnd.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.