otelpgx

README

otelpgx

Provides OpenTelemetry instrumentation for the jackc/pgx library.

Requirements

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

Usage

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)
}

See options.go for the full list of options.

Documentation

Index

• Constants
• type Option
  • func WithAttributes(attrs ...attribute.KeyValue) Option
  • func WithDisableSQLStatementInAttributes() Option
  • func WithIncludeQueryParameters() Option
  • func WithSpanNameFunc(fn SpanNameFunc) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
  • func WithTrimSQLInSpanName() Option
• type SpanNameFunc
• type Tracer
  • func NewTracer(opts ...Option) *Tracer
  • func (t *Tracer) TraceBatchEnd(ctx context.Context, _ *pgx.Conn, data pgx.TraceBatchEndData)
  • func (t *Tracer) TraceBatchQuery(ctx context.Context, conn *pgx.Conn, data pgx.TraceBatchQueryData)
  • func (t *Tracer) TraceBatchStart(ctx context.Context, conn *pgx.Conn, data pgx.TraceBatchStartData) context.Context
  • func (t *Tracer) TraceConnectEnd(ctx context.Context, data pgx.TraceConnectEndData)
  • func (t *Tracer) TraceConnectStart(ctx context.Context, data pgx.TraceConnectStartData) context.Context
  • func (t *Tracer) TraceCopyFromEnd(ctx context.Context, _ *pgx.Conn, data pgx.TraceCopyFromEndData)
  • func (t *Tracer) TraceCopyFromStart(ctx context.Context, conn *pgx.Conn, data pgx.TraceCopyFromStartData) context.Context
  • func (t *Tracer) TracePrepareEnd(ctx context.Context, _ *pgx.Conn, data pgx.TracePrepareEndData)
  • func (t *Tracer) TracePrepareStart(ctx context.Context, conn *pgx.Conn, data pgx.TracePrepareStartData) context.Context
  • func (t *Tracer) TraceQueryEnd(ctx context.Context, _ *pgx.Conn, data pgx.TraceQueryEndData)
  • func (t *Tracer) TraceQueryStart(ctx context.Context, conn *pgx.Conn, data pgx.TraceQueryStartData) context.Context

Constants

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")
	// BatchSizeKey represents the batch size.
	BatchSizeKey = attribute.Key("pgx.batch.size")
	// 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")
)

Types

type Option

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

Option specifies instrumentation configuration options.

func WithAttributes

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

WithAttributes specifies additional attributes to be added to the span.

func WithDisableSQLStatementInAttributes

func WithDisableSQLStatementInAttributes() Option

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

func WithIncludeQueryParameters

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 WithSpanNameFunc

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 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 SpanNameFunc

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 Tracer

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

Tracer is a wrapper around the pgx tracer interfaces which instrument queries.

func NewTracer

func NewTracer(opts ...Option) *Tracer

NewTracer returns a new Tracer.

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.