Documentation
¶
Overview ¶
Package otelsql instruments the database/sql package.
otelsql will trace every interface from database/sql/driver package which has context except driver.Pinger.
Index ¶
- func Open(driverName, dataSourceName string, options ...Option) (*sql.DB, error)
- func OpenDB(c driver.Connector, options ...Option) *sql.DB
- func Register(driverName string, options ...Option) (string, error)
- func RegisterDBStatsMetrics(db *sql.DB, opts ...Option) error
- func Version() string
- func WrapDriver(dri driver.Driver, options ...Option) driver.Driver
- type Event
- type Method
- type Option
- func WithAttributes(attributes ...attribute.KeyValue) Option
- func WithMeterProvider(provider metric.MeterProvider) Option
- func WithSpanNameFormatter(spanNameFormatter SpanNameFormatter) Option
- func WithSpanOptions(opts SpanOptions) Option
- func WithTracerProvider(provider trace.TracerProvider) Option
- type OptionFunc
- type SpanNameFormatter
- type SpanOptions
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Open ¶ added in v0.13.0
Open is a wrapper over sql.Open with OTel instrumentation.
Example ¶
package main import ( "database/sql/driver" "github.com/XSAM/otelsql" ) var mysqlDSN = "root:otel_password@db" func main() { // Connect to database db, err := otelsql.Open("mysql", mysqlDSN) if err != nil { panic(err) } defer db.Close() }
Output:
func OpenDB ¶ added in v0.13.0
OpenDB is a wrapper over sql.OpenDB with OTel instrumentation.
Example ¶
package main import ( "database/sql/driver" "github.com/XSAM/otelsql" ) var connector = driver.Connector(nil) func main() { // Connect to database db := otelsql.OpenDB(connector) defer db.Close() }
Output:
func Register ¶
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 ¶
package main import ( "database/sql/driver" "github.com/XSAM/otelsql" ) 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 db.Close() }
Output:
func RegisterDBStatsMetrics ¶ added in v0.13.0
RegisterDBStatsMetrics register sql.DBStats metrics with OTel instrumentation.
func WrapDriver ¶
WrapDriver takes a SQL driver and wraps it with OTel instrumentation.
Example ¶
package main import ( "database/sql" "database/sql/driver" "github.com/XSAM/otelsql" ) var ( dri = otelsql.NewMockDriver() mysqlDSN = "root:otel_password@db" ) func main() { otDriver := otelsql.WrapDriver(dri) connector, err := otDriver.(driver.DriverContext).OpenConnector(mysqlDSN) if err != nil { panic(err) } // Connect to database db := sql.OpenDB(connector) defer db.Close() }
Output:
Types ¶
type Event ¶
type Event string
Event specifics events in the database/sql package.
const (
EventRowsNext Event = "sql.rows.next"
)
type Method ¶
type Method string
Method specifics operation in the database/sql package.
const ( MethodConnectorConnect Method = "sql.connector.connect" MethodConnPing Method = "sql.conn.ping" MethodConnExec Method = "sql.conn.exec" MethodConnQuery Method = "sql.conn.query" MethodConnPrepare Method = "sql.conn.prepare" MethodConnBeginTx Method = "sql.conn.begin_tx" MethodConnResetSession Method = "sql.conn.reset_session" MethodTxCommit Method = "sql.tx.commit" MethodTxRollback Method = "sql.tx.rollback" MethodStmtExec Method = "sql.stmt.exec" MethodStmtQuery Method = "sql.stmt.query" MethodRows Method = "sql.rows" )
type Option ¶
type Option interface {
// Apply sets the Option value of a config.
Apply(*config)
}
Option is the interface that applies a configuration option.
func WithAttributes ¶
WithAttributes specifies attributes that will be set to each span.
func WithMeterProvider ¶ added in v0.13.0
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 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)
type SpanNameFormatter ¶
type SpanNameFormatter interface {
Format(ctx context.Context, method Method, query string) string
}
SpanNameFormatter is an interface that used to format 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 // AllowRoot, if set to true, will create root spans in absence of existing spans or even context. AllowRoot bool }
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.