atsql

README

atsql

Package atsql provides a wrapper for database/sql/driver.Drivers for tracing database operations as spans of a transaction traced by Atatus.

To instrument a driver, you can simply swap your application's calls to sql.Register and sql.Open to atsql.Register and atsql.Open respectively. The atsql.Register function accepts zero or more options to influence how tracing is performed.

Documentation

Overview

Package atsql provides wrappers for tracing SQL query spans.

Index

• Constants
• func Open(driverName, dataSourceName string) (*sql.DB, error)
• func QuerySignature(query string) string
• func Register(name string, driver driver.Driver, opts ...WrapOption)
• func Wrap(driver driver.Driver, opts ...WrapOption) driver.Driver
• type DSNInfo
• type DSNParserFunc
  • func DriverDSNParser(driverName string) DSNParserFunc
• type WrapOption
  • func WithDSNParser(f DSNParserFunc) WrapOption
  • func WithDriverName(name string) WrapOption

Constants

const DriverPrefix = "apm/"

DriverPrefix should be used as a driver name prefix when registering via sql.Register.

Functions

func Open

func Open(driverName, dataSourceName string) (*sql.DB, error)

Open opens a database with the given driver and data source names, as in sql.Open. The driver name should be one registered via the Register function in this package.

func QuerySignature

func QuerySignature(query string) string

QuerySignature returns the "signature" for a query: a high level description of the operation.

For DDL statements (CREATE, DROP, ALTER, etc.), we we only report the first keyword, on the grounds that these statements are not expected to be common within the hot code paths of an application. For SELECT, INSERT, and UPDATE, and DELETE, we attempt to extract the first table name. If we are unable to identify the table name, we simply omit it.

func Register

func Register(name string, driver driver.Driver, opts ...WrapOption)

Register registers a traced version of the given driver.

The name and driver values should be the same as given to sql.Register: the name of the driver (e.g. "postgres"), and the driver (e.g. &github.com/lib/pq.Driver{}).

func Wrap

func Wrap(driver driver.Driver, opts ...WrapOption) driver.Driver

Wrap wraps a database/sql/driver.Driver such that the driver's database methods are traced. The tracer will be obtained from the context supplied to methods that accept it.

Types

type DSNInfo

type DSNInfo struct {
	// Address is the database server address specified by the DSN.
	Address string

	// Port is the database server port specified by the DSN.
	Port int

	// Database is the name of the specific database identified by the DSN.
	Database string

	// User is the username that the DSN specifies for authenticating the
	// database connection.
	User string
}

DSNInfo contains information from a database-specific data source name.

type DSNParserFunc

type DSNParserFunc func(dsn string) DSNInfo

DSNParserFunc is the type of a function that can be used for parsing a data source name, and returning the corresponding Info.

func DriverDSNParser

func DriverDSNParser(driverName string) DSNParserFunc

DriverDSNParser returns the DSNParserFunc for the registered driver. If there is no such registered driver, the parser function that is returned will return empty DSNInfo structures.

type WrapOption

type WrapOption func(*tracingDriver)

WrapOption is an option that can be supplied to Wrap.

func WithDSNParser

func WithDSNParser(f DSNParserFunc) WrapOption

WithDSNParser returns a WrapOption which sets the function to use for parsing the data source name. If WithDSNParser is not supplied to Wrap, the function to use will be inferred from the driver name.

func WithDriverName

func WithDriverName(name string) WrapOption

WithDriverName returns a WrapOption which sets the underlying driver name to the specified value. If WithDriverName is not supplied to Wrap, the driver name will be inferred from the driver supplied to Wrap.