otsql

README

otsql

OpenTelemetry SQL database driver wrapper, not official.

Add an otsql wrapper to your existing database code to instrument the interactions with the database.

First version transformed from ocsql.

Install

$ go get -u github.com/j2gg0s/otsql

Usage

To use otsql with your application, register an otsql wrapper of a database driver as shown below.

Example:

import (
    "database/sql"

    "github.com/j2gg0s/otsql"
    _ "github.com/lib/pq"
)

var dsn = "postgres://otsql_user:otsql_password@localhost/otsql_db?sslmode=disable"

driverName, err := otsql.Register("postgres", otsql.WithQuery(true))
if err != nil {
    panic(err)
}

db, err := sql.Open(driverName, dsn)
if err != nil {
    panic(err)
}
defer db.Close()

Finally database drivers that support the driver.Connector interface can be wrapped directly by otsql without the need for otsql to register a driver.Driver.

Example:

import (
    "database/sql"

    "github.com/j2gg0s/otsql"
    _ "github.com/lib/pq"
)

var dsn = "postgres://otsql_user:otsql_password@localhost/otsql_db?sslmode=disable"

connector, err := pq.NewConnector(dsn)
if err != nil {
    panic(err)
}

db := sql.OpenDB(
    WrapConnector(connector, otsql.WithQuery(true)))
defer db.Close()

See more specific case in example/.

Metric And Span

Metric	Search suffix	Tags
Latency in microsecond	go.sql/latency	sql.instance, sql.method, sql.status

If use RecordStats, all metric supprt tag sql.instance.

Metric	Search suffix
The number of connections currently in use	go.sql.conn.in_use
The number of idle connections	go.sql.conn.idle
The total number of connections wait for	go.sql.conn.wait
The total number of connections closed because of SetMaxIdleConns	go.sql.conn.idle_closed
The total number of connections closed because of SetConnMaxLifetime	go.sql.conn.lifetime_closed
The total time blocked by waiting for a new connection, nanosecond	go.sql.conn.wait_ns

Test

We add wrap to gorm and run its test with a forked repo j2gg0s/gorm .

Documentation

Index

• func RecordStats(db *sql.DB, instanceName string) (err error)
• func Register(driverName string, options ...TraceOption) (string, error)
• func Wrap(dri driver.Driver, options ...TraceOption) driver.Driver
• func WrapConn(c driver.Conn, options ...TraceOption) driver.Conn
• func WrapConnector(dc driver.Connector, options ...TraceOption) driver.Connector
• type TraceOption
  • func WithAllowRoot(b bool) TraceOption
  • func WithDefaultLabels(attrs ...label.KeyValue) TraceOption
  • func WithInstanceName(instanceName string) TraceOption
  • func WithLastInsertID(b bool) TraceOption
  • func WithOptions(options TraceOptions) TraceOption
  • func WithPing(b bool) TraceOption
  • func WithQuery(b bool) TraceOption
  • func WithQueryParams(b bool) TraceOption
  • func WithRowsAffected(b bool) TraceOption
  • func WithRowsClose(b bool) TraceOption
  • func WithRowsNext(b bool) TraceOption
  • func WithSpanNameFormatter(formatter func(context.Context, string, string) string) TraceOption
• type TraceOptions

Functions

func RecordStats

func RecordStats(db *sql.DB, instanceName string) (err error)

RecordStats records database statistics for provided sql.DB. The interval is controlled by meter, default more than 10 seconds.

func Register

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

Register initializes and registers our otsql wrapped database driver identified by its driverName and using provided TraceOptions. On success it returns the generated driverName to use when calling sql.Open. It is possible to register multiple wrappers for the same database driver if needing different TraceOptions for different connections.

func Wrap

func Wrap(dri driver.Driver, options ...TraceOption) driver.Driver

Wrap takes a SQL driver and wraps it with OpenCensus instrumentation.

func WrapConn

func WrapConn(c driver.Conn, options ...TraceOption) driver.Conn

WrapConn allows an existing driver.Conn to be wrapped by otsql.

func WrapConnector

func WrapConnector(dc driver.Connector, options ...TraceOption) driver.Connector

WrapConnector allows wrapping a database driver.Connector which eliminates the need to register otsql as an available driver.Driver.

Types

type TraceOption

type TraceOption func(*TraceOptions)

TraceOption allows for managing otsql configuration using functional options.

func WithAllowRoot

func WithAllowRoot(b bool) TraceOption

WithAllowRoot if set to true, will allow otsql to create root spans in absence of exisiting spans or even context. Default is to not trace otsql calls if no existing parent span is found in context or when using methods not taking context.

func WithDefaultLabels

func WithDefaultLabels(attrs ...label.KeyValue) TraceOption

WithDefaultLabels will be set to each span as default.

func WithInstanceName

func WithInstanceName(instanceName string) TraceOption

WithInstanceName sets database instance name.

func WithLastInsertID

func WithLastInsertID(b bool) TraceOption

WithLastInsertID if set to true, will enable the creation of spans on LastInsertId calls.

func WithOptions

func WithOptions(options TraceOptions) TraceOption

WithOptions sets our otsql tracing middleware options through a single TraceOptions object.

func WithPing

func WithPing(b bool) TraceOption

WithPing if set to true, will enable the creation of spans on Ping requests.

func WithQuery

func WithQuery(b bool) TraceOption

WithQuery if set to true, will enable recording of sql queries in spans. Only allow this if it is safe to have queries recorded with respect to security.

func WithQueryParams

func WithQueryParams(b bool) TraceOption

WithQueryParams if set to true, will enable recording of parameters used with parametrized queries. Only allow this if it is safe to have parameters recorded with respect to security. This setting is a noop if the Query option is set to false.

func WithRowsAffected

func WithRowsAffected(b bool) TraceOption

WithRowsAffected if set to true, will enable the creation of spans on RowsAffected calls.

func WithRowsClose

func WithRowsClose(b bool) TraceOption

WithRowsClose if set to true, will enable the creation of spans on RowsClose calls.

func WithRowsNext

func WithRowsNext(b bool) TraceOption

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

func WithSpanNameFormatter

func WithSpanNameFormatter(formatter func(context.Context, string, string) string) TraceOption

WithSpanNameFormatter sets name for each span.

type TraceOptions

type TraceOptions struct {
	// AllowRoot, if set to true, will allow otsql to create root spans in
	// absence of existing spans or even context.
	// Default is to not trace otsql calls if no existing parent span is found
	// in context or when using methods not taking context.
	AllowRoot bool

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

	// Query, if set to true, will enable recording of sql queries in spans.
	// Only allow this if it is safe to have queries recorded with respect to
	// security.
	Query bool

	// QueryParams, if set to true, will enable recording of parameters used
	// with parametrized queries. Only allow this if it is safe to have
	// parameters recorded with respect to security.
	// This setting is a noop if the Query option is set to false.
	QueryParams bool

	// RowsAffected, if set to true, will enable the creation of spans on
	// RowsAffected calls.
	RowsAffected bool

	// LastInsertID, if set to true, will enable the creation of spans on
	// LastInsertId calls.
	LastInsertID bool

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

	// RowsClose, if set to true, will enable the creation of spans on RowsClose
	// calls.
	RowsClose bool

	// SpanNameFormatter will be called to produce span's name.
	// Default use method as span name
	SpanNameFormatter func(ctx context.Context, method string, query string) string

	// DefaultLabels will be set to each span as default.
	DefaultLabels []label.KeyValue

	// InstanceName identifies database.
	InstanceName string
}

TraceOptions holds configuration of our otsql tracing middleware. 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.