otelsql

package module
v0.0.0-...-e34857e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 16, 2023 License: Apache-2.0 Imports: 18 Imported by: 1

README

otelsql

ci codecov Go Report Card Documentation

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 and a docker-compose example for details.

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.20 amd64
Ubuntu 1.19 amd64
Ubuntu 1.20 386
Ubuntu 1.19 386
MacOS 1.20 amd64
MacOS 1.19 amd64
Windows 1.20 amd64
Windows 1.19 amd64
Windows 1.20 386
Windows 1.19 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

Examples

Constants

This section is empty.

Variables

This section is empty.

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

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/LeonPev/otelsql"
)

var connector = driver.Connector(nil)

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

Output:

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

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/LeonPev/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 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 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 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 interface {
	Format(ctx context.Context, method Method, query string) string
}

SpanNameFormatter is an interface that used to format span names. TODO(Sam): change this to function instead of interface.

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.