README
¶
OpenTracing-compatible SQL driver wrapper for Golang
This package is an implementation of a SQL driver wrapper with tracing capabilities, compatible with Opentracing API.
Usage
Register a new database driver by passing an instance created by calling NewTracingDriver:
var driver *sql.Driver
var tracer opentracing.Tracer
// init driver, tracer.
...
sql.Register("opentracing-sql", otsql.NewTracingDriver(driver, tracer))
db, err := sql.Open("opentracing-sql", ...)
// use db handle as usual.
By default, runtime-based naming function will be used, which will set the span name according to the name of the function being called (e.g. conn.QueryContext).
It's also possible to specify your own naming function:
otsql.NewTracingDriver(driver, tracer, otsql.SpanNameFunction(customNameFunction))
Name function format:
type SpanNameFunc func(context.Context) string
Note that only calls to context-aware DB functions will be traced (e.g. db.QueryContext).
Comparison with existing packages
There is an existing package https://github.com/ExpansiveWorlds/instrumentedsql which uses the same approach by wrapping an existing driver with a tracer, however the current implementation provides the following features:
- Pass custom naming function to name spans according to your needs.
- Option to enable/disable logging of SQL queries.
The following features from instrumentedsql package are not supported:
- Passing a custom logger.
- Support of cloud.google.com/go/trace.
- Don't log exact query args.
- Creating spans for LastInsertId, RowsAffected.
Documentation
References
Documentation
¶
Overview ¶
package sql provides SQL driver wrapper with tracing capabilities, compatible with Opentracing API.
Index ¶
- Variables
- func NewTracingDriver(d driver.Driver, t opentracing.Tracer, options ...func(*tracingDriver)) driver.Driver
- func SaveQuery(f SpanNameFunc) func(*tracingDriver)
- func SetTagQuery(tag string)
- func SpanNameFunction(f SpanNameFunc) func(*tracingDriver)
- func WithSpanObserver(obsFunc func(context.Context, opentracing.Span, string)) func(*tracingDriver)
- type SpanNameFunc
Constants ¶
This section is empty.
Variables ¶
var ErrUnsupported = errors.New("operation unsupported by the underlying driver")
ErrUnsupported is an error returned when the underlying driver doesn't provide a given function.
Functions ¶
func NewTracingDriver ¶
func NewTracingDriver(d driver.Driver, t opentracing.Tracer, options ...func(*tracingDriver)) driver.Driver
TracingDriver creates and returns a new SQL driver with tracing capabilities.
func SaveQuery ¶
func SaveQuery(f SpanNameFunc) func(*tracingDriver)
SaveQuery is an option for saving SQL queries.
func SetTagQuery ¶
func SetTagQuery(tag string)
SetTagQuery sets a span tag for SQL queries. Use in init funcs only.
func SpanNameFunction ¶
func SpanNameFunction(f SpanNameFunc) func(*tracingDriver)
SpanNameFunction is an option for using a custom span naming function.
func WithSpanObserver ¶
WithSpanObserver allows you to modify the span's tags for every span created.
Types ¶
type SpanNameFunc ¶
SpanNameFunc defines a function which returns a name for the span which is being created on traceable operations. Passing span naming function is optional, however it gives the user a way to use a custom naming strategy. To allow getting some more information related to the current call, the context, which is passed with the call, is propagated to the naming function.
Source Files