Documentation

Index

• Variables
• func RecordStats(db *sql.DB, interval time.Duration) (fnStop func())
• func Register(driverName string, options ...TraceOption) (string, error)
• func RegisterAllViews()
• func Wrap(d 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 WithAllTraceOptions() TraceOption
  • func WithAllowRoot(b bool) TraceOption
  • func WithDefaultAttributes(attrs ...trace.Attribute) TraceOption
  • func WithDisableErrSkip(b bool) 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 WithSampler(sampler trace.Sampler) TraceOption
• type TraceOptions

Variables

var (
	// GoSQLInstance is the SQL instance name.
	GoSQLInstance, _ = tag.NewKey("go_sql_instance")
	// GoSQLMethod is the SQL method called.
	GoSQLMethod, _ = tag.NewKey("go_sql_method")
	// GoSQLError is the error received while calling a SQL method.
	GoSQLError, _ = tag.NewKey("go_sql_error")
	// GoSQLStatus identifies success vs. error from the SQL method response.
	GoSQLStatus, _ = tag.NewKey("go_sql_status")
)

The following tags are applied to stats recorded by this package.

var (
	MeasureLatencyMs         = stats.Float64("go.sql/latency", "The latency of calls in milliseconds", stats.UnitMilliseconds)
	MeasureOpenConnections   = stats.Int64("go.sql/connections/open", "Count of open connections in the pool", stats.UnitDimensionless)
	MeasureIdleConnections   = stats.Int64("go.sql/connections/idle", "Count of idle connections in the pool", stats.UnitDimensionless)
	MeasureActiveConnections = stats.Int64("go.sql/connections/active", "Count of active connections in the pool", stats.UnitDimensionless)
	MeasureWaitCount         = stats.Int64("go.sql/connections/wait_count", "The total number of connections waited for", stats.UnitDimensionless)
	MeasureWaitDuration      = stats.Float64("go.sql/connections/wait_duration", "The total time blocked waiting for a new connection", stats.UnitMilliseconds)
	MeasureIdleClosed        = stats.Int64("go.sql/connections/idle_closed", "The total number of connections closed due to SetMaxIdleConns", stats.UnitDimensionless)
	MeasureLifetimeClosed    = stats.Int64("go.sql/connections/lifetime_closed", "The total number of connections closed due to SetConnMaxLifetime", stats.UnitDimensionless)
)

The following measures are supported for use in custom views.

var (
	SQLClientLatencyView = &view.View{
		Name:        "go.sql/client/latency",
		Description: "The distribution of latencies of various calls in milliseconds",
		Measure:     MeasureLatencyMs,
		Aggregation: DefaultMillisecondsDistribution,
		TagKeys:     []tag.Key{GoSQLInstance, GoSQLMethod, GoSQLError, GoSQLStatus},
	}

	SQLClientCallsView = &view.View{
		Name:        "go.sql/client/calls",
		Description: "The number of various calls of methods",
		Measure:     MeasureLatencyMs,
		Aggregation: view.Count(),
		TagKeys:     []tag.Key{GoSQLInstance, GoSQLMethod, GoSQLError, GoSQLStatus},
	}

	SQLClientOpenConnectionsView = &view.View{
		Name:        "go.sql/db/connections/open",
		Description: "The number of open connections",
		Measure:     MeasureOpenConnections,
		Aggregation: view.LastValue(),
		TagKeys:     []tag.Key{GoSQLInstance},
	}

	SQLClientIdleConnectionsView = &view.View{
		Name:        "go.sql/db/connections/idle",
		Description: "The number of idle connections",
		Measure:     MeasureIdleConnections,
		Aggregation: view.LastValue(),
		TagKeys:     []tag.Key{GoSQLInstance},
	}

	SQLClientActiveConnectionsView = &view.View{
		Name:        "go.sql/db/connections/active",
		Description: "The number of active connections",
		Measure:     MeasureActiveConnections,
		Aggregation: view.LastValue(),
		TagKeys:     []tag.Key{GoSQLInstance},
	}

	SQLClientWaitCountView = &view.View{
		Name:        "go.sql/db/connections/wait_count",
		Description: "The total number of connections waited for",
		Measure:     MeasureWaitCount,
		Aggregation: view.LastValue(),
		TagKeys:     []tag.Key{GoSQLInstance},
	}

	SQLClientWaitDurationView = &view.View{
		Name:        "go.sql/db/connections/wait_duration",
		Description: "The total time blocked waiting for a new connection",
		Measure:     MeasureWaitDuration,
		Aggregation: view.LastValue(),
		TagKeys:     []tag.Key{GoSQLInstance},
	}

	SQLClientIdleClosedView = &view.View{
		Name:        "go.sql/db/connections/idle_closed_count",
		Description: "The total number of connections closed due to SetMaxIdleConns",
		Measure:     MeasureIdleClosed,
		Aggregation: view.LastValue(),
		TagKeys:     []tag.Key{GoSQLInstance},
	}

	SQLClientLifetimeClosedView = &view.View{
		Name:        "go.sql/db/connections/lifetime_closed_count",
		Description: "The total number of connections closed due to SetConnMaxLifetime",
		Measure:     MeasureLifetimeClosed,
		Aggregation: view.LastValue(),
		TagKeys:     []tag.Key{GoSQLInstance},
	}

	DefaultViews = []*view.View{
		SQLClientLatencyView, SQLClientCallsView, SQLClientOpenConnectionsView,
		SQLClientIdleConnectionsView, SQLClientActiveConnectionsView,
		SQLClientWaitCountView, SQLClientWaitDurationView,
		SQLClientIdleClosedView, SQLClientLifetimeClosedView,
	}
)

Package ocsql provides some convenience views. You still need to register these views for data to actually be collected. You can use the RegisterAllViews function for this.

var AllTraceOptions = TraceOptions{
	AllowRoot:    true,
	Ping:         true,
	RowsNext:     true,
	RowsClose:    true,
	RowsAffected: true,
	LastInsertID: true,
	Query:        true,
	QueryParams:  true,
}

AllTraceOptions has all tracing options enabled.

var (
	DefaultMillisecondsDistribution = view.Distribution(
		0.0,
		0.001,
		0.005,
		0.01,
		0.05,
		0.1,
		0.5,
		1.0,
		1.5,
		2.0,
		2.5,
		5.0,
		10.0,
		25.0,
		50.0,
		100.0,
		200.0,
		400.0,
		600.0,
		800.0,
		1000.0,
		1500.0,
		2000.0,
		2500.0,
		5000.0,
		10000.0,
		20000.0,
		40000.0,
		100000.0,
		200000.0,
		500000.0)
)

Default distributions used by views in this package

func RecordStats

func RecordStats(db *sql.DB, interval time.Duration) (fnStop func())

RecordStats records database statistics for provided sql.DB at the provided interval.

func Register

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

Register initializes and registers our ocsql 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 RegisterAllViews

func RegisterAllViews()

RegisterAllViews registers all ocsql views to enable collection of stats.

func Wrap

func Wrap(d 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 ocsql.

func WrapConnector

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

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

type TraceOption

type TraceOption func(o *TraceOptions)

TraceOption allows for managing ocsql configuration using functional options.

func WithAllTraceOptions

func WithAllTraceOptions() TraceOption

WithAllTraceOptions enables all available trace options.

func WithAllowRoot

func WithAllowRoot(b bool) TraceOption

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

func WithDefaultAttributes

func WithDefaultAttributes(attrs ...trace.Attribute) TraceOption

WithDefaultAttributes will be set to each span as default.

func WithDisableErrSkip

func WithDisableErrSkip(b bool) TraceOption

WithDisableErrSkip, if set to true, will suppress driver.ErrSkip errors in spans.

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 ocsql 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 WithSampler

func WithSampler(sampler trace.Sampler) TraceOption

WithSampler will be used on span creation.

type TraceOptions

type TraceOptions struct {
	// AllowRoot, if set to true, will allow ocsql to create root spans in
	// absence of existing spans or even context.
	// Default is to not trace ocsql 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

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

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

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

	// DefaultAttributes will be set to each span as default.
	DefaultAttributes []trace.Attribute

	// InstanceName identifies database.
	InstanceName string

	// DisableErrSkip, if set to true, will suppress driver.ErrSkip errors in spans.
	DisableErrSkip bool

	// Sampler to use when creating spans.
	Sampler trace.Sampler
}

TraceOptions holds configuration of our ocsql 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.

Package Files

• dbstats_go1.11.go
• driver.go
• driver_go1.10.go
• observability.go
• options.go