otelsql

README

otelsql

It is an OpenTelemetry instrumentation for Golang database/sql, a port from https://github.com/open-telemetry/opentelemetry-go-contrib/pull/505.

It can only instrument traces for the present.

Install

$ go get github.com/XSAM/otelsql

Features

Feature	Description	Status	Reason
Rows, RowsClose	Will enable the creation of spans on corresponding calls.	Enabled by default, can't be disabled	We need to know the status of Rows
Query	If set to true, will enable recording of sql queries in spans.	Enabled by default	Will populate db.statement, which is a conditional attribute.
Ping	If set to true, will enable the creation of spans on Ping requests.	Implemented	Ping has context argument, but it might no needs to record.
RowsNext	If set to true, will enable the creation of events on corresponding calls. This can result in many events.	Implemented	It provides more visibility.
DisableErrSkip	If set to true, will suppress driver.ErrSkip errors in spans.	Implemented	ErrSkip error might annoying
RecordError	If set to true, will invoke the specified function which decides if the error should be recorded or not	Implemented	This gives the opportunity to check driver specific error codes and not record those that might not be a relevant error (eg. MySQL 1062 Duplicate Entry might be handled in the app and should not be recorded as an error).
AllowRoot	If set to true, will allow otelsql to create root spans in absence of existing spans or even context.	Implemented	It might helpful while debugging missing operations.
RowsAffected, LastInsertID	If set to true, will enable the creation of spans on RowsAffected/LastInsertId calls.	Dropped	Don't know its use cases. We might add this later based on the users' feedback.
QueryParams	If set to true, will enable recording of parameters used with parametrized queries.	Dropped	It will cause high cardinality values and security problems.

Example

See example

Compatibility

This project is tested on the following systems.

OS	Go Version	Architecture
Ubuntu	1.17	amd64
Ubuntu	1.16	amd64
Ubuntu	1.17	386
Ubuntu	1.16	386
MacOS	1.17	amd64
MacOS	1.16	amd64
Windows	1.17	amd64
Windows	1.16	amd64
Windows	1.17	386
Windows	1.16	386

While this project should work for other systems, no compatibility guarantees are made for those systems currently.

The project follows the Release Policy to support major Go releases.

Why port this?

Based on this comment, OpenTelemetry SIG team like to see broader usage and community consensus on an approach before they commit to the level of support that would be required of a package in contrib. But it is painful for users without a stable version, and they have to use replacement in go.mod to use this instrumentation.

Therefore, I host this module independently for convenience and make improvements based on users' feedback.

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 Register(driverName string, dbSystem string, options ...Option) (string, error)
• func Version() string
• func WrapDriver(dri driver.Driver, dbSystem string, options ...Option) driver.Driver
• type Event
• type Method
• type Option
  • func WithAttributes(attributes ...attribute.KeyValue) Option
  • func WithSpanNameFormatter(spanNameFormatter SpanNameFormatter) Option
  • func WithSpanOptions(opts SpanOptions) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
• type OptionFunc
  • func (f OptionFunc) Apply(c *config)
• type SpanNameFormatter
• type SpanOptions

Functions

func Register

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

Register initializes and registers our 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. Parameter dbSystem is an identifier for the database management system (DBMS) product being used.

For more information, see semantic conventions for database https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/database.md

func Version

func Version() string

Version is the current release version of otelsql in use.

func WrapDriver

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

WrapDriver takes a SQL driver and wraps it with OTel instrumentation. Parameter dbSystem is an identifier for the database management system (DBMS) product being used.

For more information, see semantic conventions for database https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/database.md

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

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

WithAttributes specifies attributes that will be set to each span.

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.