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

• 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 WithLogger(l Logger) Opt
  • func WithTracer(t Tracer) Opt
• type Span
• type Tracer

Examples

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

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 (
	"context"
	"database/sql"
	"log"

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

	"github.com/ExpansiveWorlds/instrumentedsql"
	"github.com/ExpansiveWorlds/instrumentedsql/google"
)

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

	sql.Register("instrumented-mysql", instrumentedsql.WrapDriver(mysql.MySQLDriver{}, instrumentedsql.WithTracer(google.NewTracer()), instrumentedsql.WithLogger(logger)))
	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, but 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 (Opentracing)

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

package main

import (
	"context"
	"database/sql"
	"log"

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

	"github.com/ExpansiveWorlds/instrumentedsql"
	"github.com/ExpansiveWorlds/instrumentedsql/opentracing"
)

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

	sql.Register("instrumented-mysql", instrumentedsql.WrapDriver(mysql.MySQLDriver{}, instrumentedsql.WithTracer(opentracing.NewTracer()), instrumentedsql.WithLogger(logger)))
	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(*wrappedDriver)

Opt is a functional option type for the wrapped driver

func WithLogger

func WithLogger(l Logger) Opt

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

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