sql

Documentation

Overview

Package sqltraced provides a traced version of any driver implementing the database/sql/driver interface. To trace jmoiron/sqlx, see https://godoc.org/github.com/DataDog/dd-trace-go/tracer/contrib/sqlxtraced.

Example

To trace the sql calls, you just need to open your sql.DB with OpenTraced. All calls through this sql.DB object will then be traced.

package main

import (
	"log"

	sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql"
	"github.com/lib/pq"
)

func main() {
	// OpenTraced will first register a traced version of the driver and then will return the sql.DB object
	// that holds the connection with the database.
	// The third argument is used to specify the name of the service under which traces will appear in the Datadog app.
	db, err := sqltrace.OpenTraced(&pq.Driver{}, "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable", "web-backend")
	if err != nil {
		log.Fatal(err)
	}

	// All calls through the database/sql API will then be traced.
	rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()
}

Example (Context)

If you want to link your db calls with existing traces, you need to use the context version of the database/sql API. Just make sure you are passing the parent span within the context.

package main

import (
	"context"
	"log"

	sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql"
	"github.com/DataDog/dd-trace-go/tracer"
	"github.com/lib/pq"
)

func main() {
	// OpenTraced will first register a traced version of the driver and then will return the sql.DB object
	// that holds the connection with the database.
	// The third argument is used to specify the name of the service under which traces will appear in the Datadog app.
	db, err := sqltrace.OpenTraced(&pq.Driver{}, "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable", "web-backend")
	if err != nil {
		log.Fatal(err)
	}

	// We create a parent span and put it within the context.
	span := tracer.NewRootSpan("postgres.parent", "web-backend", "query-parent")
	ctx := tracer.ContextWithSpan(context.Background(), span)

	// We need to use the context version of the database/sql API
	// in order to link this call with the parent span.
	db.PingContext(ctx)
	rows, _ := db.QueryContext(ctx, "SELECT * FROM city LIMIT 5")
	rows.Close()

	stmt, _ := db.PrepareContext(ctx, "INSERT INTO city(name) VALUES($1)")
	stmt.Exec("New York")
	stmt, _ = db.PrepareContext(ctx, "SELECT name FROM city LIMIT $1")
	rows, _ = stmt.Query(1)
	rows.Close()
	stmt.Close()

	tx, _ := db.BeginTx(ctx, nil)
	tx.ExecContext(ctx, "INSERT INTO city(name) VALUES('New York')")
	rows, _ = tx.QueryContext(ctx, "SELECT * FROM city LIMIT 5")
	rows.Close()
	stmt, _ = tx.PrepareContext(ctx, "SELECT name FROM city LIMIT $1")
	rows, _ = stmt.Query(1)
	rows.Close()
	stmt.Close()
	tx.Commit()

	// Calling span.Finish() will send the span into the tracer's buffer
	// and then being processed.
	span.Finish()
}

Example (MySQL)

You can trace all drivers implementing the database/sql/driver interface. For example, you can trace the go-sql-driver/mysql with the following code.

package main

import (
	"log"

	sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql"
	"github.com/go-sql-driver/mysql"
)

func main() {
	// OpenTraced will first register a traced version of the driver and then will return the sql.DB object
	// that holds the connection with the database.
	// The third argument is used to specify the name of the service under which traces will appear in the Datadog app.
	db, err := sqltrace.OpenTraced(&mysql.MySQLDriver{}, "user:password@/dbname", "web-backend")
	if err != nil {
		log.Fatal(err)
	}

	// All calls through the database/sql API will then be traced.
	rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()
}

Index

• func Open(driverName, dataSourceName, service string) (*sql.DB, error)
• func OpenTraced(driver driver.Driver, dataSourceName, service string, trcv ...*tracer.Tracer) (*sql.DB, error)
• func Register(driverName string, driver driver.Driver, trcv ...*tracer.Tracer)

Examples

• Package
• Package (Context)
• Package (MySQL)
• OpenTraced
• OpenTraced (Tracer)
• Register
• Register (Tracer)

Functions

func Open

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

Open extends the usual API of sql.Open so you can specify the name of the service under which the traces will appear in the datadog app.

func OpenTraced

func OpenTraced(driver driver.Driver, dataSourceName, service string, trcv ...*tracer.Tracer) (*sql.DB, error)

OpenTraced will first register the traced version of the `driver` if not yet registered and will then open a connection with it. This is usually the only function to use when there is no need for the granularity offered by Register and Open. The last parameter is optional and enables you to use a custom tracer.

Example

OpenTraced will first register a traced version of the driver and then will return the sql.DB object that holds the connection with the database.

package main

import (
	"log"

	sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql"
	"github.com/lib/pq"
)

func main() {
	// The first argument is a reference to the driver to trace.
	// The second argument is the dataSourceName.
	// The third argument is used to specify the name of the service under which traces will appear in the Datadog app.
	// The last argument allows you to specify a custom tracer to use for tracing.
	db, err := sqltrace.OpenTraced(&pq.Driver{}, "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable", "web-backend")
	if err != nil {
		log.Fatal(err)
	}

	// Use the database/sql API as usual and see traces appear in the Datadog app.
	rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()
}

Example (Tracer)

You can use a custom tracer by passing it through the optional last argument of OpenTraced.

package main

import (
	"log"

	sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql"
	"github.com/DataDog/dd-trace-go/tracer"
	"github.com/lib/pq"
)

func main() {
	// Create and customize a new tracer that will forward 50% of generated traces to the agent.
	// (useful to manage resource usage in high-throughput environments)
	trc := tracer.NewTracer()
	trc.SetSampleRate(0.5)

	// Pass your custom tracer through the last argument of OpenTraced to trace your db calls with it.
	db, err := sqltrace.OpenTraced(&pq.Driver{}, "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable", "web-backend", trc)
	if err != nil {
		log.Fatal(err)
	}

	// Use the database/sql API as usual and see traces appear in the Datadog app.
	rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()
}

func Register

func Register(driverName string, driver driver.Driver, trcv ...*tracer.Tracer)

Register takes a driver and registers a traced version of this one. The last parameter is optional and enables you to use a custom tracer.

Example

If you need more granularity, you can register the traced driver seperately from the Open call.

package main

import (
	"log"

	sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql"
	"github.com/lib/pq"
)

func main() {
	// Register a traced version of your driver.
	sqltrace.Register("postgres", &pq.Driver{})

	// Returns a sql.DB object that holds the traced connection to the database.
	// Note: the sql.DB object returned by sql.Open will not be traced so make sure to use sql.Open.
	db, _ := sqltrace.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable", "web-backend")
	defer db.Close()

	// Use the database/sql API as usual and see traces appear in the Datadog app.
	rows, err := db.Query("SELECT name FROM users WHERE age=?", 27)
	if err != nil {
		log.Fatal(err)
	}
	defer rows.Close()
}

Example (Tracer)

You can use a custom tracer by passing it through the optional last argument of Register.

package main

import (
	sqltrace "github.com/DataDog/dd-trace-go/contrib/database/sql"
	"github.com/DataDog/dd-trace-go/tracer"
	"github.com/lib/pq"
)

func main() {
	// Create and customize a new tracer that will forward 50% of generated traces to the agent.
	// (useful to manage resource usage in high-throughput environments)
	trc := tracer.NewTracer()
	trc.SetSampleRate(0.5)

	// Register a traced version of your driver and specify to use the previous tracer
	// to send the traces to the agent.
	sqltrace.Register("postgres", &pq.Driver{}, trc)

	// Returns a sql.DB object that holds the traced connection to the database.
	// Note: the sql.DB object returned by sql.Open will not be traced so make sure to use sql.Open.
	db, _ := sqltrace.Open("postgres", "postgres://pqgotest:password@localhost/pqgotest?sslmode=disable", "web-backend")
	defer db.Close()
}