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 instruments traces and metrics.

Install

$ go get github.com/XSAM/otelsql

Usage

This project provides four different ways to instrument database/sql:

otelsql.Open, otelsql.OpenDB, otesql.Register and otelsql.WrapDriver.

And then use otelsql.RegisterDBStatsMetrics to instrument sql.DBStats with metrics.

db, err := otelsql.Open("mysql", mysqlDSN, otelsql.WithAttributes(
	semconv.DBSystemMySQL,
))
if err != nil {
	panic(err)
}
defer db.Close()

err = otelsql.RegisterDBStatsMetrics(db, otelsql.WithAttributes(
	semconv.DBSystemMySQL,
))
if err != nil {
	panic(err)
}

Check Option for more features like adding context propagation to SQL queries when enabling WithSQLCommenter.

See godoc for details.

Blog

Getting started with otelsql, the OpenTelemetry instrumentation for Go SQL, is a blog post that explains how to use otelsql in miutes.

Examples

This project provides two docker-compose examples to show how to use it.

• The stdout example is a simple example to show how to use it with a MySQL database. It prints the trace data to stdout and serves metrics data via prometheus client.
• The otel-collector example is a more complex example to show how to use it with a MySQL database and an OpenTelemetry Collector. It sends the trace data and metrics data to an OpenTelemetry Collector. Then, it shows data visually on Jaeger and Prometheus servers.

Trace Instruments

It creates spans on corresponding methods.

Use SpanOptions to adjust creation of spans.

Metric Instruments

Name	Description	Units	Instrument Type	Value Type	Attribute Key(s)	Attribute Values
db.sql.latency	The latency of calls in milliseconds	ms	Histogram	float64	status	ok, error
					method	method name, like sql.conn.query
db.sql.connection.max_open	Maximum number of open connections to the database		Asynchronous Gauge	int64
db.sql.connection.open	The number of established connections both in use and idle		Asynchronous Gauge	int64	status	idle, inuse
db.sql.connection.wait	The total number of connections waited for		Asynchronous Counter	int64
db.sql.connection.wait_duration	The total time blocked waiting for a new connection	ms	Asynchronous Counter	float64
db.sql.connection.closed_max_idle	The total number of connections closed due to SetMaxIdleConns		Asynchronous Counter	int64
db.sql.connection.closed_max_idle_time	The total number of connections closed due to SetConnMaxIdleTime		Asynchronous Counter	int64
db.sql.connection.closed_max_lifetime	The total number of connections closed due to SetConnMaxLifetime		Asynchronous Counter	int64

Compatibility

This project is tested on the following systems.

OS	Go Version	Architecture
Ubuntu	1.23	amd64
Ubuntu	1.22	amd64
Ubuntu	1.23	386
Ubuntu	1.22	386
MacOS	1.23	amd64
MacOS	1.22	amd64
Windows	1.23	amd64
Windows	1.22	amd64
Windows	1.23	386
Windows	1.22	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.

Communication

I use GitHub discussions/issues for most communications. Feel free to contact me on CNCF slack.

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 AttributesGetter
• type Event
• type InstrumentAttributesGetter
• type Method
• type Option
  • func WithAttributes(attributes ...attribute.KeyValue) Option
  • func WithAttributesGetter(attributesGetter AttributesGetter) Option
  • func WithInstrumentAttributesGetter(instrumentAttributesGetter InstrumentAttributesGetter) Option
  • func WithMeterProvider(provider metric.MeterProvider) Option
  • func WithSQLCommenter(enabled bool) 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 SpanFilter
• type SpanNameFormatter
• type SpanOptions

Examples

• Open
• OpenDB
• Register
• WrapDriver

Functions

func Open

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

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

func OpenDB

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

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

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

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

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

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

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

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

WithAttributes specifies attributes that will be set to each span.

func WithAttributesGetter

func WithAttributesGetter(attributesGetter AttributesGetter) Option

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

func WithInstrumentAttributesGetter

func WithInstrumentAttributesGetter(instrumentAttributesGetter InstrumentAttributesGetter) Option

WithInstrumentAttributesGetter takes InstrumentAttributesGetter 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)

type SpanFilter

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

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.