otelsql – github.com/XSAM/otelsql Index | Examples | Files | Directories

package otelsql

import "github.com/XSAM/otelsql"

Package otelsql instruments the database/sql package.

otelsql will trace every interface from database/sql/driver package which has context except driver.Pinger.

Index

Examples

Functions

func AttributesFromDSN 

func AttributesFromDSN(dsn string) []attribute.KeyValue

AttributesFromDSN returns attributes extracted from a DSN string. It makes the best effort to retrieve values for semconv.ServerAddressKey and semconv.ServerPortKey.

Example

Code:play  

package main

import (
	"database/sql"

	semconv "go.opentelemetry.io/otel/semconv/v1.30.0"

	"github.com/XSAM/otelsql"
)

func init() {
	sql.Register("mysql", otelsql.NewMockDriver())
}

var mysqlDSN = "root:otel_password@db"

func main() {
	attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemNameMySQL)

	// Connect to database
	db, err := otelsql.Open("mysql", mysqlDSN, otelsql.WithAttributes(
		attrs...,
	))
	if err != nil {
		panic(err)
	}
	defer func() { _ = db.Close() }()

	// Register DB stats to meter
	err = otelsql.RegisterDBStatsMetrics(db, otelsql.WithAttributes(
		attrs...,
	))
	if err != nil {
		panic(err)
	}
}

func Open 

func Open(driverName, dataSourceName string, options ...Option) (*sql.DB, error)

Open is a wrapper over sql.Open with OTel instrumentation.

Example

Code:play  

package main

import (
	"database/sql"

	"github.com/XSAM/otelsql"
)

func init() {
	sql.Register("mysql", otelsql.NewMockDriver())
}

var mysqlDSN = "root:otel_password@db"

func main() {
	// Connect to database
	db, err := otelsql.Open("mysql", mysqlDSN)
	if err != nil {
		panic(err)
	}
	defer func() { _ = db.Close() }()
}

func OpenDB 

func OpenDB(c driver.Connector, options ...Option) *sql.DB

OpenDB is a wrapper over sql.OpenDB with OTel instrumentation.

Example

Code:play  

package main

import (
	"database/sql"
	"database/sql/driver"

	"github.com/XSAM/otelsql"
)

func init() {
	sql.Register("mysql", otelsql.NewMockDriver())
}

var (
	dri      = otelsql.NewMockDriver()
	mysqlDSN = "root:otel_password@db"
)

func main() {
	driverContext, ok := dri.(driver.DriverContext)
	if !ok {
		panic("driver does not implement driver.DriverContext")
	}
	connector, err := driverContext.OpenConnector(mysqlDSN)
	if err != nil {
		panic(err)
	}

	// Connect to database
	db := otelsql.OpenDB(connector)
	defer func() { _ = db.Close() }()
}

func Register 

func Register(driverName string, options ...Option) (string, error)

Register initializes and registers OTel wrapped database driver identified by its driverName, using provided Option. It is possible to register multiple wrappers for the same database driver if needing different Option for different connections.

Example

Code:play  

package main

import (
	"database/sql"

	"github.com/XSAM/otelsql"
)

func init() {
	sql.Register("mysql", otelsql.NewMockDriver())
}

var mysqlDSN = "root:otel_password@db"

func main() {
	// Register an OTel driver
	driverName, err := otelsql.Register("mysql")
	if err != nil {
		panic(err)
	}

	// Connect to database
	db, err := otelsql.Open(driverName, mysqlDSN)
	if err != nil {
		panic(err)
	}
	defer func() { _ = db.Close() }()
}

func RegisterDBStatsMetrics 

func RegisterDBStatsMetrics(db *sql.DB, opts ...Option) error

RegisterDBStatsMetrics register sql.DBStats metrics with OTel instrumentation.

func Version 

func Version() string

Version is the current release version of otelsql in use.

func WrapDriver 

func WrapDriver(dri driver.Driver, options ...Option) driver.Driver

WrapDriver takes a SQL driver and wraps it with OTel instrumentation.

Example

Code:play  

package main

import (
	"database/sql"
	"database/sql/driver"

	"github.com/XSAM/otelsql"
)

func init() {
	sql.Register("mysql", otelsql.NewMockDriver())
}

var (
	dri      = otelsql.NewMockDriver()
	mysqlDSN = "root:otel_password@db"
)

func main() {
	otDriver := otelsql.WrapDriver(dri)

	driverContext, ok := otDriver.(driver.DriverContext)
	if !ok {
		panic("driver does not implement driver.DriverContext")
	}
	connector, err := driverContext.OpenConnector(mysqlDSN)
	if err != nil {
		panic(err)
	}

	// Connect to database
	db := sql.OpenDB(connector)
	defer func() { _ = db.Close() }()
}

Types

type AttributesGetter 

type AttributesGetter func(ctx context.Context, method Method, query string, args []driver.NamedValue) []attribute.KeyValue

AttributesGetter provides additional attributes on spans creation.

type Event 

type Event string

Event specifics events in the database/sql package. 

const (
	// EventRowsNext is triggered during driver.Rows.Next iteration to track each row fetching operation.
	EventRowsNext Event = "sql.rows.next"
)

type InstrumentAttributesGetter 

type InstrumentAttributesGetter func(ctx context.Context, method Method, query string, args []driver.NamedValue) []attribute.KeyValue

InstrumentAttributesGetter provides additional attributes while recording metrics to instruments.

type InstrumentErrorAttributesGetter 

type InstrumentErrorAttributesGetter func(err error) []attribute.KeyValue

InstrumentErrorAttributesGetter provides additional error-related attributes while recording metrics to instruments.

type Method 

type Method string

Method specifics operation in the database/sql package. 

const (
	// MethodConnectorConnect is used when driver.Connector.Connect is called to establish a new connection.
	MethodConnectorConnect Method = "sql.connector.connect"
	// MethodConnPing is used with driver.Pinger.Ping to verify database connection is alive.
	MethodConnPing Method = "sql.conn.ping"
	// MethodConnExec is used with driver.ExecerContext.ExecContext for direct query execution through a connection.
	MethodConnExec Method = "sql.conn.exec"
	// MethodConnQuery is used with driver.QueryerContext.QueryContext for executing queries directly through a connection.
	MethodConnQuery Method = "sql.conn.query"
	// MethodConnPrepare is used with driver.ConnPrepareContext.PrepareContext for creating prepared statements.
	MethodConnPrepare Method = "sql.conn.prepare"
	// MethodConnBeginTx is used with driver.ConnBeginTx.BeginTx for starting a new transaction.
	MethodConnBeginTx Method = "sql.conn.begin_tx"
	// MethodConnResetSession is used with driver.SessionResetter.ResetSession to reset connection session state.
	MethodConnResetSession Method = "sql.conn.reset_session"
	// MethodTxCommit is used with driver.Tx.Commit to commit a transaction.
	MethodTxCommit Method = "sql.tx.commit"
	// MethodTxRollback is used with driver.Tx.Rollback to rollback a transaction.
	MethodTxRollback Method = "sql.tx.rollback"
	// MethodStmtExec is used with driver.StmtExecContext.ExecContext to execute a prepared statement.
	MethodStmtExec Method = "sql.stmt.exec"
	// MethodStmtQuery is used with driver.StmtQueryContext.QueryContext to query using a prepared statement.
	MethodStmtQuery Method = "sql.stmt.query"
	// MethodRows is used to track the lifecycle of driver.Rows returned by query operations.
	MethodRows Method = "sql.rows"
)

type Option 

type Option interface {
	// Apply sets the Option value of a config.
	Apply(cfg *config)
}

Option is the interface that applies a configuration option.

func WithAttributes 

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

WithAttributes specifies attributes that will be set to each span and measurement.

func WithAttributesGetter 

func WithAttributesGetter(attributesGetter AttributesGetter) Option

WithAttributesGetter takes AttributesGetter that will be called on every span creations.

func WithDisableSkipErrMeasurement 

func WithDisableSkipErrMeasurement(disable bool) Option

WithDisableSkipErrMeasurement controls whether driver.ErrSkip is treated as an error in measurements. When enabled, measurements with driver.ErrSkip will be recorded as status=ok instead of error.

func WithInstrumentAttributesGetter 

func WithInstrumentAttributesGetter(instrumentAttributesGetter InstrumentAttributesGetter) Option

WithInstrumentAttributesGetter takes InstrumentAttributesGetter that will be called every time metric is recorded to instruments.

func WithInstrumentErrorAttributesGetter 

func WithInstrumentErrorAttributesGetter(instrumentErrorAttributesGetter InstrumentErrorAttributesGetter) Option

WithInstrumentErrorAttributesGetter takes InstrumentErrorAttributesGetter that will be called every time metric is recorded to instruments.

func WithMeterProvider 

func WithMeterProvider(provider metric.MeterProvider) Option

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

func WithSQLCommenter 

func WithSQLCommenter(enabled bool) Option

WithSQLCommenter will enable or disable context propagation for database by injecting a comment into SQL statements.

e.g., a SQL query 

SELECT * from FOO

will become 

SELECT * from FOO /*traceparent='00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',tracestate='congo%3Dt61rcWkgMzE%2Crojo%3D00f067aa0ba902b7'*/

This option defaults to disable.

Notice: This option is EXPERIMENTAL and may be changed or removed in a later release.

func WithSpanNameFormatter 

func WithSpanNameFormatter(spanNameFormatter SpanNameFormatter) Option

WithSpanNameFormatter takes an interface that will be called on every operation and the returned string will become the span name.

func WithSpanOptions 

func WithSpanOptions(opts SpanOptions) Option

WithSpanOptions specifies configuration for span to decide whether to enable some features.

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.

type OptionFunc 

type OptionFunc func(*config)

OptionFunc implements the Option interface.

func (OptionFunc) Apply 

func (f OptionFunc) Apply(c *config)

Apply sets the Option value of a config by calling the wrapped function.

type SpanFilter 

type SpanFilter func(ctx context.Context, method Method, query string, args []driver.NamedValue) bool

SpanFilter is a function that determines whether a span should be created for a given SQL operation. It returns true if the span should be created, or false to skip span creation.

type SpanNameFormatter 

type SpanNameFormatter func(ctx context.Context, method Method, query string) string

SpanNameFormatter supports formatting span names.

type SpanOptions 

type SpanOptions struct {
	// Ping, if set to true, will enable the creation of spans on Ping requests.
	Ping bool

	// RowsNext, if set to true, will enable the creation of events in spans on RowsNext
	// calls. This can result in many events.
	RowsNext bool

	// DisableErrSkip, if set to true, will suppress driver.ErrSkip errors in spans.
	DisableErrSkip bool

	// DisableQuery if set to true, will suppress db.statement in spans.
	DisableQuery bool

	// RecordError, if set, will be invoked with the current error, and if the func returns true
	// the record will be recorded on the current span.
	//
	// If this is not set it will default to record all errors (possible not ErrSkip, see option
	// DisableErrSkip).
	RecordError func(err error) bool

	// OmitConnResetSession if set to true will suppress sql.conn.reset_session spans
	OmitConnResetSession bool

	// OmitConnPrepare if set to true will suppress sql.conn.prepare spans
	OmitConnPrepare bool

	// OmitConnQuery if set to true will suppress sql.conn.query spans
	OmitConnQuery bool

	// OmitRows if set to true will suppress sql.rows spans
	OmitRows bool

	// OmitConnectorConnect if set to true will suppress sql.connector.connect spans
	OmitConnectorConnect bool

	// SpanFilter, if set, will be invoked before each call to create a span. If it returns
	// false, the span will not be created.
	SpanFilter SpanFilter
}

SpanOptions holds configuration of tracing span to decide whether to enable some features. By default all options are set to false intentionally when creating a wrapped driver and provide the most sensible default with both performance and security in mind.

Source Files

commenter.go config.go conn.go connector.go doc.go driver.go helpers.go instruments.go methods.go option.go rows.go sql.go stmt.go tx.go utils.go version.go

Directories

PathSynopsis
internal
Version
v0.39.0 (latest)
Published
Jun 5, 2025
Platform
linux/amd64
Imports
20 packages
Last checked
now –

Tools for package owners.