package ocsql

Import Path
	contrib.go.opencensus.io/integrations/ocsql (on go.dev)

Dependency Relation
	imports 14 packages, and imported by 2 packages

Involved Source Files

	      dbstats_go1.11.go
	      driver.go
	      driver_go1.10.go
	      observability.go
	      options.go
Package-Level Type Names (total 10, in which 2 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type TraceOption (func)
		TraceOption allows for managing ocsql configuration using functional options.

		As Outputs Of (at least 11, all are exported)
			func WithAllowRoot(b bool) TraceOption
			func WithAllTraceOptions() TraceOption
			func WithDefaultAttributes(attrs ...trace.Attribute) 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
		As Inputs Of (at least 5, all are exported)
			func Register(driverName string, options ...TraceOption) (string, error)
			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
			func golang.org/x/pkgsite/internal/database.RegisterOCWrapper(driverName string, opts ...TraceOption) (string, error)

	 type TraceOptions (struct)
		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.

		Fields (total 9, all are exported)
			AllowRoot bool
				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.

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

			LastInsertID bool
				LastInsertID, if set to true, will enable the creation of spans on
				LastInsertId calls.

			Ping bool
				Ping, if set to true, will enable the creation of spans on Ping requests.

			Query 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.

			QueryParams 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.

			RowsAffected bool
				RowsAffected, if set to true, will enable the creation of spans on
				RowsAffected calls.

			RowsClose bool
				RowsClose, if set to true, will enable the creation of spans on RowsClose
				calls.

			RowsNext bool
				RowsNext, if set to true, will enable the creation of spans on RowsNext
				calls. This can result in many spans.

		As Inputs Of (at least 5, in which 1 are exported)
			func WithOptions(options TraceOptions) TraceOption
			/* 4+ unexporteds ... *//* 4+ unexporteds: */
			func wrapConn(parent driver.Conn, options TraceOptions) driver.Conn
			func wrapDriver(d driver.Driver, o TraceOptions) driver.Driver
			func wrapRows(ctx context.Context, parent driver.Rows, options TraceOptions) driver.Rows
			func wrapStmt(stmt driver.Stmt, query string, options TraceOptions) driver.Stmt
		As Types Of (only one, which is exported)
			  var AllTraceOptions

	/* 8 unexporteds ... *//* 8 unexporteds: */
	 type conn (interface)

		Methods (total 10, all are exported)
			( T) Begin() (driver.Tx, error)
				Begin starts and returns a new transaction.

				Deprecated: Drivers should implement ConnBeginTx instead (or additionally).

			( T) BeginTx(ctx context.Context, opts driver.TxOptions) (driver.Tx, error)
				BeginTx starts and returns a new transaction.
				If the context is canceled by the user the sql package will
				call Tx.Rollback before discarding and closing the connection.

				This must check opts.Isolation to determine if there is a set
				isolation level. If the driver does not support a non-default
				level and one is set or if there is a non-default isolation level
				that is not supported, an error must be returned.

				This must also check opts.ReadOnly to determine if the read-only
				value is true to either set the read-only transaction property if supported
				or return an error if it is not supported.

			( T) Close() error
				Close invalidates and potentially stops any current
				prepared statements and transactions, marking this
				connection as no longer in use.

				Because the sql package maintains a free pool of
				connections and only calls Close when there's a surplus of
				idle connections, it shouldn't be necessary for drivers to
				do their own connection caching.

				Drivers must ensure all network calls made by Close
				do not block indefinitely (e.g. apply a timeout).

			( T) Exec(query string, args []driver.Value) (driver.Result, error)
			( T) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Result, error)
			( T) Ping(ctx context.Context) error
			( T) Prepare(query string) (driver.Stmt, error)
				Prepare returns a prepared statement, bound to this connection.

			( T) PrepareContext(ctx context.Context, query string) (driver.Stmt, error)
				PrepareContext returns a prepared statement, bound to this connection.
				context is for the preparation of the statement,
				it must not store the context within the statement itself.

			( T) Query(query string, args []driver.Value) (driver.Rows, error)
			( T) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (driver.Rows, error)
		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			*ocConn
		Implements (at least 10, in which 9 are exported)
			 T : database/sql/driver.Conn
			 T : database/sql/driver.ConnBeginTx
			 T : database/sql/driver.ConnPrepareContext
			 T : database/sql/driver.Execer
			 T : database/sql/driver.ExecerContext
			 T : database/sql/driver.Pinger
			 T : database/sql/driver.Queryer
			 T : database/sql/driver.QueryerContext
			 T : io.Closer
			/* at least one unexported ... *//* at least one unexported: */
			 T : golang.org/x/pkgsite/internal/database.iconn

	 type ocConn (struct)
		ocConn implements driver.Conn

		Fields (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			options TraceOptions
			parent driver.Conn
		Methods (total 10, all are exported)
			(*T) Begin() (driver.Tx, error)
			(*T) BeginTx(ctx context.Context, opts driver.TxOptions) (tx driver.Tx, err error)
			(*T) Close() error
			( T) Exec(query string, args []driver.Value) (res driver.Result, err error)
			( T) ExecContext(ctx context.Context, query string, args []driver.NamedValue) (res driver.Result, err error)
			( T) Ping(ctx context.Context) (err error)
			( T) Prepare(query string) (stmt driver.Stmt, err error)
			(*T) PrepareContext(ctx context.Context, query string) (stmt driver.Stmt, err error)
			( T) Query(query string, args []driver.Value) (rows driver.Rows, err error)
			( T) QueryContext(ctx context.Context, query string, args []driver.NamedValue) (rows driver.Rows, err error)
		Implements (at least 11, in which 9 are exported)
			*T : database/sql/driver.Conn
			*T : database/sql/driver.ConnBeginTx
			*T : database/sql/driver.ConnPrepareContext
			 T : database/sql/driver.Execer
			 T : database/sql/driver.ExecerContext
			 T : database/sql/driver.Pinger
			 T : database/sql/driver.Queryer
			 T : database/sql/driver.QueryerContext
			*T : io.Closer
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			*T : conn
			*T : golang.org/x/pkgsite/internal/database.iconn

	 type ocDriver (struct)
		ocDriver implements driver.Driver

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			connector driver.Connector
			options TraceOptions
			parent driver.Driver
		Methods (total 4, all are exported)
			( T) Connect(ctx context.Context) (driver.Conn, error)
			( T) Driver() driver.Driver
			( T) Open(name string) (driver.Conn, error)
				Open implements driver.Driver

			( T) OpenConnector(name string) (driver.Connector, error)
		Implements (at least 3, all are exported)
			 T : database/sql/driver.Connector
			 T : database/sql/driver.Driver
			 T : database/sql/driver.DriverContext

	 type ocResult (struct)
		ocResult implements driver.Result

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			ctx context.Context
			options TraceOptions
			parent driver.Result
		Methods (total 2, both are exported)
			( T) LastInsertId() (id int64, err error)
			( T) RowsAffected() (cnt int64, err error)
		Implements (at least 2, both are exported)
			 T : database/sql.Result
			 T : database/sql/driver.Result

	 type ocRows (struct)
		ocRows implements driver.Rows and all enhancement interfaces except
		driver.RowsColumnTypeScanType.

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			ctx context.Context
			options TraceOptions
			parent driver.Rows
		Methods (total 9, all are exported)
			( T) Close() (err error)
			( T) ColumnTypeDatabaseTypeName(index int) string
				ColumnTypeDatabaseTypeName calls the implements the driver.RowsColumnTypeDatabaseTypeName for ocRows.
				It returns the the underlying result of ColumnTypeDatabaseTypeName from the ocRows.parent
				if the parent implements driver.RowsColumnTypeDatabaseTypeName.

			( T) ColumnTypeLength(index int) (length int64, ok bool)
				ColumnTypeLength calls the implements the driver.RowsColumnTypeLength for ocRows.
				It returns the the underlying result of ColumnTypeLength from the ocRows.parent
				if the parent implements driver.RowsColumnTypeLength.

			( T) ColumnTypeNullable(index int) (nullable, ok bool)
				ColumnTypeNullable calls the implements the driver.RowsColumnTypeNullable for ocRows.
				It returns the the underlying result of ColumnTypeNullable from the ocRows.parent
				if the parent implements driver.RowsColumnTypeNullable.

			( T) ColumnTypePrecisionScale(index int) (precision, scale int64, ok bool)
				ColumnTypePrecisionScale calls the implements the driver.RowsColumnTypePrecisionScale for ocRows.
				It returns the the underlying result of ColumnTypePrecisionScale from the ocRows.parent
				if the parent implements driver.RowsColumnTypePrecisionScale.

			( T) Columns() []string
			( T) HasNextResultSet() bool
				HasNextResultSet calls the implements the driver.RowsNextResultSet for ocRows.
				It returns the the underlying result of HasNextResultSet from the ocRows.parent
				if the parent implements driver.RowsNextResultSet.

			( T) Next(dest []driver.Value) (err error)
			( T) NextResultSet() error
				NextResultsSet calls the implements the driver.RowsNextResultSet for ocRows.
				It returns the the underlying result of NextResultSet from the ocRows.parent
				if the parent implements driver.RowsNextResultSet.

		Implements (at least 7, all are exported)
			 T : database/sql/driver.Rows
			 T : database/sql/driver.RowsColumnTypeDatabaseTypeName
			 T : database/sql/driver.RowsColumnTypeLength
			 T : database/sql/driver.RowsColumnTypeNullable
			 T : database/sql/driver.RowsColumnTypePrecisionScale
			 T : database/sql/driver.RowsNextResultSet
			 T : io.Closer

	 type ocStmt (struct)
		ocStmt implements driver.Stmt

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			options TraceOptions
			parent driver.Stmt
			query string
		Methods (total 6, all are exported)
			( T) Close() error
			( T) Exec(args []driver.Value) (res driver.Result, err error)
			( T) ExecContext(ctx context.Context, args []driver.NamedValue) (res driver.Result, err error)
			( T) NumInput() int
			( T) Query(args []driver.Value) (rows driver.Rows, err error)
			( T) QueryContext(ctx context.Context, args []driver.NamedValue) (rows driver.Rows, err error)
		Implements (at least 4, all are exported)
			 T : database/sql/driver.Stmt
			 T : database/sql/driver.StmtExecContext
			 T : database/sql/driver.StmtQueryContext
			 T : io.Closer

	 type ocTx (struct)
		ocTx implemens driver.Tx

		Fields (total 3, none are exported)
			/* 3 unexporteds ... *//* 3 unexporteds: */
			ctx context.Context
			options TraceOptions
			parent driver.Tx
		Methods (total 2, both are exported)
			( T) Commit() (err error)
			( T) Rollback() (err error)
		Implements (at least one exported)
			 T : database/sql/driver.Tx

	 type withRowsColumnTypeScanType (interface)
		withRowsColumnTypeScanType is the same as the driver.RowsColumnTypeScanType
		interface except it omits the driver.Rows embedded interface.
		If the original driver.Rows implementation wrapped by ocsql supports
		RowsColumnTypeScanType we enable the original method implementation in the
		returned driver.Rows from wrapRows by doing a composition with ocRows.

		Methods (only one, which is exported)
			( T) ColumnTypeScanType(index int) reflect.Type
		Implemented By (at least 3, in which 2 are exported)
			 database/sql/driver.RowsColumnTypeScanType (interface)
			*github.com/jackc/pgx/v4/stdlib.Rows
			/* at least one unexported ... *//* at least one unexported: */
			*github.com/lib/pq.rows


Package-Level Functions (total 26, in which 17 are exported)

	 func RecordStats(db *sql.DB, interval time.Duration) (fnStop func())
		RecordStats records database statistics for provided sql.DB at the provided
		interval.

	 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()
		RegisterAllViews registers all ocsql views to enable collection of stats.

	 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 WithAllTraceOptions() TraceOption
		WithAllTraceOptions enables all available trace options.

	 func WithDefaultAttributes(attrs ...trace.Attribute) TraceOption
		WithDefaultAttributes will be set to each span as default.

	 func WithLastInsertID(b bool) TraceOption
		WithLastInsertID if set to true, will enable the creation of spans on
		LastInsertId calls.

	 func WithOptions(options TraceOptions) TraceOption
		WithOptions sets our ocsql tracing middleware options through a single
		TraceOptions object.

	 func WithPing(b bool) TraceOption
		WithPing if set to true, will enable the creation of spans on Ping requests.

	 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(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(b bool) TraceOption
		WithRowsAffected if set to true, will enable the creation of spans on
		RowsAffected calls.

	 func WithRowsClose(b bool) TraceOption
		WithRowsClose if set to true, will enable the creation of spans on RowsClose
		calls.

	 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 Wrap(d driver.Driver, options ...TraceOption) driver.Driver
		Wrap takes a SQL driver and wraps it with OpenCensus instrumentation.

	 func WrapConn(c driver.Conn, options ...TraceOption) driver.Conn
		WrapConn allows an existing driver.Conn to be wrapped by ocsql.

	 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.

	/* 9 unexporteds ... *//* 9 unexporteds: */
	 func argToAttr(key string, val interface{}) trace.Attribute
	 func namedParamsAttr(args []driver.NamedValue) []trace.Attribute
	 func paramsAttr(args []driver.Value) []trace.Attribute
	 func recordCallStats(ctx context.Context, method string) func(err error)
	 func setSpanStatus(span *trace.Span, err error)
	 func wrapConn(parent driver.Conn, options TraceOptions) driver.Conn
	 func wrapDriver(d driver.Driver, o TraceOptions) driver.Driver
	 func wrapRows(ctx context.Context, parent driver.Rows, options TraceOptions) driver.Rows
		wrapRows returns a struct which conforms to the driver.Rows interface.
		ocRows implements all enhancement interfaces that have no effect on
		sql/database logic in case the underlying parent implementation lacks them.
		Currently the one exception is RowsColumnTypeScanType which does not have a
		valid zero value. This interface is tested for and only enabled in case the
		parent implementation supports it.

	 func wrapStmt(stmt driver.Stmt, query string, options TraceOptions) driver.Stmt
Package-Level Variables (total 29, in which 23 are exported)

	  var AllTraceOptions TraceOptions
		AllTraceOptions has all tracing options enabled.

	  var DefaultMillisecondsDistribution *view.Aggregation
		Default distributions used by views in this package

	  var DefaultViews []*view.View
		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 GoSQLError tag.Key
		GoSQLError is the error received while calling a SQL method.

	  var GoSQLMethod tag.Key
		GoSQLMethod is the SQL method called.

	  var GoSQLStatus tag.Key
		GoSQLStatus identifies success vs. error from the SQL method response.

	  var MeasureActiveConnections *stats.Int64Measure
		The following measures are supported for use in custom views.

	  var MeasureIdleClosed *stats.Int64Measure
		The following measures are supported for use in custom views.

	  var MeasureIdleConnections *stats.Int64Measure
		The following measures are supported for use in custom views.

	  var MeasureLatencyMs *stats.Float64Measure
		The following measures are supported for use in custom views.

	  var MeasureLifetimeClosed *stats.Int64Measure
		The following measures are supported for use in custom views.

	  var MeasureOpenConnections *stats.Int64Measure
		The following measures are supported for use in custom views.

	  var MeasureWaitCount *stats.Int64Measure
		The following measures are supported for use in custom views.

	  var MeasureWaitDuration *stats.Float64Measure
		The following measures are supported for use in custom views.

	  var SQLClientActiveConnectionsView *view.View
		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 SQLClientCallsView *view.View
		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 SQLClientIdleClosedView *view.View
		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 SQLClientIdleConnectionsView *view.View
		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 SQLClientLatencyView *view.View
		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 SQLClientLifetimeClosedView *view.View
		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 SQLClientOpenConnectionsView *view.View
		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 SQLClientWaitCountView *view.View
		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 SQLClientWaitDurationView *view.View
		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.

	/* 6 unexporteds ... *//* 6 unexporteds: */
	  var attrDeprecated trace.Attribute
	  var attrMissingContext trace.Attribute
	  var errConnDone error
	  var regMu sync.Mutex
	  var valueErr tag.Mutator
		The following tags are applied to stats recorded by this package.

	  var valueOK tag.Mutator
		The following tags are applied to stats recorded by this package.

The pages are generated with Golds v0.3.2-preview. (GOOS=darwin GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.