telemetry

README

Telemetry Package

The telemetry package provides database connection wrappers with support for metrics and tracing instrumentation. It allows tracking database operations with detailed telemetry data while maintaining the original connection interface.

• Automatic span creation and management for database operations
• Request duration metrics tracking
• Request count metrics
• Error tracking and reporting
• Detailed span attributes including:
  • Command type (exec, query, batch, etc.)
  • SQL query details
  • Query arguments
  • Additional operation details

// Create telemetry-enabled database service
dbService := db.New(/* options */)
telemetryService := telemetry.New(dbService, myTelemetryImplementation)

// Start the service
if err := telemetryService.Start(context.Background()); err != nil {
    log.Fatal(err)
}
defer telemetryService.Stop(context.Background())

// Use the database with telemetry
connection := telemetryService.Connection(ctx)

The package defines the ITelemetry interface that must be implemented to provide telemetry functionality

Documentation

Index

• type Attribute
• type ConnectionWrapper
  • func (p *ConnectionWrapper) CopyFrom(ctx context.Context, tableName pgx.Identifier, columnNames []string, ...) (n int64, err error)
  • func (p *ConnectionWrapper) Exec(ctx context.Context, sql string, arguments ...any) (tag pgconn.CommandTag, err error)
  • func (p *ConnectionWrapper) InTransaction() bool
  • func (p *ConnectionWrapper) LargeObjects() pgx.LargeObjects
  • func (p *ConnectionWrapper) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
  • func (p *ConnectionWrapper) QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
  • func (p *ConnectionWrapper) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults
  • func (p *ConnectionWrapper) TransactionOptions() txmgr.Options
  • func (p *ConnectionWrapper) WithoutTransaction(ctx context.Context) context.Context
• type ISpan
• type ITelemetry
• type Service
  • func New(parent db.IStartStopConnector, telemetry ITelemetry) *Service
  • func (s *Service) Connection(ctx context.Context, opt ...conn.ConnectionOption) conn.IConnection
  • func (s *Service) Start(ctx context.Context) error
  • func (s *Service) Stop(ctx context.Context) error

Types

type Attribute

type Attribute struct {
	Key   string
	Value any
}

Attribute span attribute.

type ConnectionWrapper

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

ConnectionWrapper wrapper over iConnection with added telemetry and logs.

func (*ConnectionWrapper) CopyFrom

func (p *ConnectionWrapper) CopyFrom(ctx context.Context, tableName pgx.Identifier,
	columnNames []string, rowSrc pgx.CopyFromSource,
) (n int64, err error)

CopyFrom implements bulk data insertion into a table.

func (*ConnectionWrapper) Exec

func (p *ConnectionWrapper) Exec(ctx context.Context, sql string, arguments ...any) (tag pgconn.CommandTag, err error)

Exec executes a query without returning data.

func (*ConnectionWrapper) InTransaction

func (p *ConnectionWrapper) InTransaction() bool

InTransaction returns true if a transaction has been started.

func (*ConnectionWrapper) LargeObjects

func (p *ConnectionWrapper) LargeObjects() pgx.LargeObjects

LargeObjects supports working with large objects and is only available in trace mode.

func (*ConnectionWrapper) Query

func (p *ConnectionWrapper) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)

Query executes a query and returns the result.

func (*ConnectionWrapper) QueryRow

func (p *ConnectionWrapper) QueryRow(ctx context.Context, sql string, args ...any) pgx.Row

QueryRow executes a query and returns the result.

func (*ConnectionWrapper) SendBatch

func (p *ConnectionWrapper) SendBatch(ctx context.Context, b *pgx.Batch) pgx.BatchResults

SendBatch sends a set of queries for execution, combining all queries into one batch.

func (*ConnectionWrapper) TransactionOptions

func (p *ConnectionWrapper) TransactionOptions() txmgr.Options

TransactionOptions returns transaction parameters. If the transaction has not been started, it returns false.

func (*ConnectionWrapper) WithoutTransaction

func (p *ConnectionWrapper) WithoutTransaction(ctx context.Context) context.Context

WithoutTransaction returns a context without a transaction.

type ISpan

type ISpan interface {
	AddAttributes(attributes []Attribute)
	End()
}

ISpan interface for span.

type ITelemetry

type ITelemetry interface {
	// StartSpan starts new span. If returns nil, span is not created.
	StartSpan(ctx context.Context, name string) (context.Context, ISpan)
	// ObserveRequestDuration records request duration.
	ObserveRequestDuration(ctx context.Context, duration time.Duration)
	// ObserveRequest records request count.
	ObserveRequest(ctx context.Context)
	// ObserveRequestError records request error.
	ObserveRequestError(ctx context.Context, err error)
}

ITelemetry interface for telemetry.

type Service

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

Service wrapper for working with DB and sending telemetry.

func New

func New(parent db.IStartStopConnector, telemetry ITelemetry) *Service

New creates a new Service instance.

func (*Service) Connection

func (s *Service) Connection(ctx context.Context, opt ...conn.ConnectionOption) conn.IConnection

Connection returns an implementation of the IConnection interface.

func (*Service) Start

func (s *Service) Start(ctx context.Context) error

Start starts the service.

func (*Service) Stop

func (s *Service) Stop(ctx context.Context) error

Stop stops the service.