Documentation
¶
Overview ¶
Package sql provides functions to trace the database/sql package (https://golang.org/pkg/database/sql). It will automatically augment operations such as connections, statements and transactions with tracing.
We start by telling the package which driver we will be using. For example, if we are using "github.com/lib/pq", we would do as follows:
sqltrace.Register("pq", pq.Driver{})
db, err := sqltrace.Open("pq", "postgres://pqgotest:password@localhost...")
The rest of our application would continue as usual, but with tracing enabled.
Example ¶
package main
import (
"log"
sqltrace "github.com/lsgndln/dd-trace-go/contrib/database/sql"
"github.com/lib/pq"
)
func main() {
// The first step is to register the driver that we will be using.
sqltrace.Register("postgres", &pq.Driver{})
// Followed by a call to Open.
db, err := sqltrace.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable")
if err != nil {
log.Fatal(err)
}
// Then, we continue using the database/sql package as we normally would, with tracing.
rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
if err != nil {
log.Fatal(err)
}
defer rows.Close()
}
Output:
Example (Context) ¶
package main
import (
"context"
"log"
sqltrace "github.com/lsgndln/dd-trace-go/contrib/database/sql"
"github.com/lsgndln/dd-trace-go/ddtrace/ext"
"github.com/lsgndln/dd-trace-go/ddtrace/tracer"
"github.com/go-sql-driver/mysql"
)
func main() {
// Register the driver that we will be using (in this case mysql) under a custom service name.
sqltrace.Register("mysql", &mysql.MySQLDriver{}, sqltrace.WithServiceName("my-db"))
// Open a connection to the DB using the driver we've just registered with tracing.
db, err := sqltrace.Open("mysql", "user:password@/dbname")
if err != nil {
log.Fatal(err)
}
// Create a root span, giving name, server and resource.
span, ctx := tracer.StartSpanFromContext(context.Background(), "my-query",
tracer.SpanType(ext.SpanTypeSQL),
tracer.ServiceName("my-db"),
tracer.ResourceName("initial-access"),
)
// Subsequent spans inherit their parent from context.
rows, err := db.QueryContext(ctx, "SELECT * FROM city LIMIT 5")
if err != nil {
log.Fatal(err)
}
rows.Close()
span.Finish(tracer.WithError(err))
}
Output:
Example (DbmPropagation) ¶
package main
import (
"log"
sqltrace "github.com/lsgndln/dd-trace-go/contrib/database/sql"
"github.com/lsgndln/dd-trace-go/ddtrace/tracer"
"github.com/lib/pq"
)
func main() {
// The first step is to set the dbm propagation mode when registering the driver. Note that this can also
// be done on sqltrace.Open for more granular control over the feature.
sqltrace.Register("postgres", &pq.Driver{}, sqltrace.WithDBMPropagation(tracer.DBMPropagationModeFull))
// Followed by a call to Open.
db, err := sqltrace.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable")
if err != nil {
log.Fatal(err)
}
// Then, we continue using the database/sql package as we normally would, with tracing.
rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
if err != nil {
log.Fatal(err)
}
defer rows.Close()
}
Output:
Example (Sqlite) ¶
package main
import (
"context"
"log"
sqlite "github.com/mattn/go-sqlite3"
sqltrace "github.com/lsgndln/dd-trace-go/contrib/database/sql"
"github.com/lsgndln/dd-trace-go/ddtrace/tracer"
)
func main() {
// Register the driver that we will be using (in this case Sqlite) under a custom service name.
sqltrace.Register("sqlite", &sqlite.SQLiteDriver{}, sqltrace.WithServiceName("sqlite-example"))
// Open a connection to the DB using the driver we've just registered with tracing.
db, err := sqltrace.Open("sqlite", "./test.db")
if err != nil {
log.Fatal(err)
}
// Create a root span, giving name, server and resource.
span, ctx := tracer.StartSpanFromContext(context.Background(), "my-query",
tracer.SpanType("example"),
tracer.ServiceName("sqlite-example"),
tracer.ResourceName("initial-access"),
)
// Subsequent spans inherit their parent from context.
rows, err := db.QueryContext(ctx, "SELECT * FROM city LIMIT 5")
if err != nil {
log.Fatal(err)
}
rows.Close()
span.Finish(tracer.WithError(err))
}
Output:
Index ¶
- func Open(driverName, dataSourceName string, opts ...Option) (*sql.DB, error)
- func OpenDB(c driver.Connector, opts ...Option) *sql.DB
- func Register(driverName string, driver driver.Driver, opts ...RegisterOption)
- func WithSpanTags(ctx context.Context, tags map[string]string) context.Context
- type Option
- func WithAnalytics(on bool) Option
- func WithAnalyticsRate(rate float64) Option
- func WithChildSpansOnly() Option
- func WithCustomTag(key string, value interface{}) Option
- func WithDBMPropagation(mode tracer.DBMPropagationMode) Option
- func WithDSN(name string) Option
- func WithErrorCheck(fn func(err error) bool) Option
- func WithSQLCommentInjection(mode tracer.SQLCommentInjectionMode) Optiondeprecated
- func WithServiceName(name string) Option
- type RegisterOption
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Open ¶
Open returns connection to a DB using the traced version of the given driver. In order for Open to work, the driver must first be registered using Register. If this did not occur, Open will return an error.
func OpenDB ¶
OpenDB returns connection to a DB using the traced version of the given driver. In order for OpenDB to work, the driver must first be registered using Register. If this did not occur, OpenDB will panic.
func Register ¶
func Register(driverName string, driver driver.Driver, opts ...RegisterOption)
Register tells the sql integration package about the driver that we will be tracing. It must be called before Open, if that connection is to be traced. It uses the driverName suffixed with ".db" as the default service name.
Types ¶
type Option ¶
type Option func(*config)
Option represents an option that can be passed to Register, Open or OpenDB.
func WithAnalytics ¶
WithAnalytics enables Trace Analytics for all started spans.
func WithAnalyticsRate ¶
WithAnalyticsRate sets the sampling rate for Trace Analytics events correlated to started spans.
func WithChildSpansOnly ¶
func WithChildSpansOnly() Option
WithChildSpansOnly causes spans to be created only when there is an existing parent span in the Context.
func WithCustomTag ¶
WithCustomTag will attach the value to the span tagged by the key
func WithDBMPropagation ¶
func WithDBMPropagation(mode tracer.DBMPropagationMode) Option
WithDBMPropagation enables injection of tags as sql comments on traced queries. This includes dynamic values like span id, trace id and the sampled flag which can make queries unique for some cache implementations. Use DBMPropagationModeService if this is a concern.
Note that enabling sql comment propagation results in potentially confidential data (service names) being stored in the databases which can then be accessed by other 3rd parties that have been granted access to the database.
func WithDSN ¶
WithDSN allows the data source name (DSN) to be provided when using OpenDB and a driver.Connector. The value is used to automatically set tags on spans.
func WithErrorCheck ¶
WithErrorCheck specifies a function fn which determines whether the passed error should be marked as an error. The fn is called whenever a database/sql operation finishes with an error
func WithSQLCommentInjection
deprecated
func WithSQLCommentInjection(mode tracer.SQLCommentInjectionMode) Option
WithSQLCommentInjection enables injection of tags as sql comments on traced queries. This includes dynamic values like span id, trace id and sampling priority which can make queries unique for some cache implementations.
Deprecated: Use WithDBMPropagation instead.
func WithServiceName ¶
WithServiceName sets the given service name when registering a driver, or opening a database connection.
type RegisterOption ¶
type RegisterOption = Option
RegisterOption has been deprecated in favor of Option.
Source Files
Directories