instrumentedsql

README

instrumentedsql

A sql driver that will wrap any other driver and log/trace all its calls

How to use

Please see the documentation and examples

Roadmap

Reach API stability and decide what is in/out of scope for this package. current plan is to include tracing, logging, metrics, and anything else that might fit into a wrapper, keeping everything optional and disabled by default.

Contributing

PRs and issues are welcomed and will be responded to in a timely fashion, please contribute!

Contributors will contain all people (not companies) that have contributed to the project. LICENSE will list all copyright holders.

Documentation

Index

• Constants
• func WrapDriver(driver driver.Driver, opts ...Opt) driver.Driver
• type Logger
• type LoggerFunc
  • func (f LoggerFunc) Log(ctx context.Context, msg string, keyvals ...interface{})
• type Opt
  • func WithIncludeArgs() Opt
  • func WithLogger(l Logger) Opt
  • func WithOmitArgs() Opt
  • func WithTracer(t Tracer) Opt
• type Span
• type Tracer

Examples

• WrapDriver (Google)
• WrapDriver (JustLogging)
• WrapDriver (Opencensus)
• WrapDriver (Opentracing)

Constants

const (
	// LabelComponent ...
	LabelComponent = "component"
	// LabelQuery ...
	LabelQuery = "query"
	// LabelArgs ...
	LabelArgs = "args"
	// SQLTxBegin name for transaction begin
	SQLTxBegin = "sql-tx-begin"
	// SQLPrepare name for prepare statements
	SQLPrepare = "sql-prepare"
	// SQLConnExec name for exec statements
	SQLConnExec = "sql-conn-exec"
	// SQLPing name for pings
	SQLPing = "sql-ping"
	// SQLConnQuery name for query statements
	SQLConnQuery = "sql-conn-query"
	// SQLTxCommit name for transaction commits
	SQLTxCommit = "sql-tx-commit"
	// SQLTxRollback name for transaction rollbacks
	SQLTxRollback = "sql-tx-rollback"
	// SQLStmtClose name for statement closes
	SQLStmtClose = "sql-stmt-close"
	// SQLStmtExec name for statement exec
	SQLStmtExec = "sql-stmt-exec"
	// SQLStmtQuery name for statement query
	SQLStmtQuery = "sql-stmt-query"
	// SQLLastInsertID name for last inserted id
	SQLLastInsertID = "sql-res-lastInsertId"
	// SQLRowsAffected name for rows affected
	SQLRowsAffected = "sql-res-rowsAffected"
	// SQLRowsNext name for requesting the next set of rows
	SQLRowsNext = "sql-rows-next"
)

Functions

func WrapDriver

func WrapDriver(driver driver.Driver, opts ...Opt) driver.Driver

WrapDriver will wrap the passed SQL driver and return a new sql driver that uses it and also logs and traces calls using the passed logger and tracer The returned driver will still have to be registered with the sql package before it can be used.

Important note: Seeing as the context passed into the various instrumentation calls this package calls, Any call without a context passed will not be instrumented. Please be sure to use the ___Context() and BeginTx() function calls added in Go 1.8 instead of the older calls which do not accept a context.

Example (Google)

WrapDriverGoogle demonstrates how to call wrapDriver and register a new driver. This example uses MySQL and google tracing to illustrate this

package main

import (
	"database/sql"

	"github.com/go-sql-driver/mysql"

	"github.com/luna-duclos/instrumentedsql"
	"github.com/luna-duclos/instrumentedsql/google"
)

func main() {
	sql.Register("instrumented-mysql", instrumentedsql.WrapDriver(mysql.MySQLDriver{}, instrumentedsql.WithTracer(google.NewTracer(false))))
	db, err := sql.Open("instrumented-mysql", "connString")

	// Proceed to handle connection errors and use the database as usual
	_, _ = db, err
}

Example (JustLogging)

WrapDriverJustLogging demonstrates how to call wrapDriver and register a new driver. This example uses sqlite, and does not trace, but merely logs all calls

logger := instrumentedsql.LoggerFunc(func(ctx context.Context, msg string, keyvals ...interface{}) {
	log.Printf("%s %v", msg, keyvals)
})

sql.Register("instrumented-sqlite", instrumentedsql.WrapDriver(&sqlite3.SQLiteDriver{}, instrumentedsql.WithLogger(logger)))
db, err := sql.Open("instrumented-sqlite", "connString")

// Proceed to handle connection errors and use the database as usual
_, _ = db, err

Example (Opencensus)

WrapDriverOpencensus demonstrates how to call wrapDriver and register a new driver. This example uses MySQL and opencensus to illustrate this

package main

import (
	"database/sql"

	"github.com/go-sql-driver/mysql"
	"github.com/luna-duclos/instrumentedsql/opencensus"

	"github.com/luna-duclos/instrumentedsql"
)

func main() {
	sql.Register("instrumented-mysql", instrumentedsql.WrapDriver(mysql.MySQLDriver{}, instrumentedsql.WithTracer(opencensus.NewTracer(false))))
	db, err := sql.Open("instrumented-mysql", "connString")

	// Proceed to handle connection errors and use the database as usual
	_, _ = db, err
}

Example (Opentracing)

WrapDriverOpentracing demonstrates how to call wrapDriver and register a new driver. This example uses MySQL and opentracing to illustrate this

package main

import (
	"database/sql"

	"github.com/go-sql-driver/mysql"

	"github.com/luna-duclos/instrumentedsql"
	"github.com/luna-duclos/instrumentedsql/opentracing"
)

func main() {
	sql.Register("instrumented-mysql", instrumentedsql.WrapDriver(mysql.MySQLDriver{}, instrumentedsql.WithTracer(opentracing.NewTracer(false))))
	db, err := sql.Open("instrumented-mysql", "connString")

	// Proceed to handle connection errors and use the database as usual
	_, _ = db, err
}

Types

type Logger

type Logger interface {
	Log(ctx context.Context, msg string, keyvals ...interface{})
}

Logger is the interface needed to be implemented by any logging implementation we use, see also NewFuncLogger

type LoggerFunc

type LoggerFunc func(ctx context.Context, msg string, keyvals ...interface{})

LoggerFunc is an adapter which allows a function to be used as a Logger.

func (LoggerFunc) Log

func (f LoggerFunc) Log(ctx context.Context, msg string, keyvals ...interface{})

Log calls f(ctx, msg, keyvals...).

type Opt

type Opt func(*opts)

Opt is a functional option type for the wrapped driver

func WithIncludeArgs

func WithIncludeArgs() Opt

WithIncludeArgs will make it so that query arguments are included in logging and tracing This is the default, but can be used to override WithOmitArgs

func WithLogger

func WithLogger(l Logger) Opt

WithLogger sets the logger of the wrapped driver to the provided logger

func WithOmitArgs

func WithOmitArgs() Opt

WithOmitArgs will make it so that query arguments are omitted from logging and tracing

func WithTracer

func WithTracer(t Tracer) Opt

WithTracer sets the tracer of the wrapped driver to the provided tracer

type Span

type Span interface {
	NewChild(string) Span
	SetLabel(k, v string)
	SetError(err error)
	Finish()
}

Span is part of the interface needed to be implemented by any tracing implementation we use

type Tracer

type Tracer interface {
	GetSpan(ctx context.Context) Span
}

Tracer is the interface needed to be implemented by any tracing implementation we use