otelsql

README

database/sql instrumentation for OpenTelemetry Go

database/sql OpenTelemetry instrumentation records database queries (including Tx and Stmt queries) and reports DBStats metrics.

Installation

go get github.com/uptrace/opentelemetry-go-extra/otelsql

Usage

To instrument database/sql, you need to connect to a database using the API provided by otelsql:

sql	otelsql
sql.Open(driverName, dsn)	otelsql.Open(driverName, dsn)
sql.OpenDB(connector)	otelsql.OpenDB(connector)

import (
	"github.com/uptrace/opentelemetry-go-extra/otelsql"
	semconv "go.opentelemetry.io/otel/semconv/v1.10.0"
)

db, err := otelsql.Open("sqlite", "file::memory:?cache=shared",
	otelsql.WithAttributes(semconv.DBSystemSqlite),
	otelsql.WithDBName("mydb"))
if err != nil {
	panic(err)
}

// db is *sql.DB

And then use context-aware API to propagate the active span via context:

var num int
if err := db.QueryRowContext(ctx, "SELECT 42").Scan(&num); err != nil {
	panic(err)
}

See example for details.

Options

Both otelsql.Open and otelsql.OpenDB accept the same options:

• WithAttributes configures attributes that are used to create a span.
• WithDBName configures a db.name attribute.
• WithDBSystem configures a db.system attribute. When possible, you should prefer using WithAttributes and semconv, for example, otelsql.WithAttributes(semconv.DBSystemSqlite).

sqlboiler

You can use otelsql to instrument sqlboiler ORM:

import (
    "github.com/uptrace/opentelemetry-go-extra/otelsql"
    semconv "go.opentelemetry.io/otel/semconv/v1.10.0"
)

db, err := otelsql.Open("postgres", "dbname=fun user=abc",
    otelsql.WithAttributes(semconv.DBSystemPostgreSQL))
if err != nil {
  return err
}

boil.SetDB(db)

GORM 1

You can use otelsql to instrument GORM 1:

import (
    "github.com/jinzhu/gorm"
    "github.com/uptrace/opentelemetry-go-extra/otelsql"
    semconv "go.opentelemetry.io/otel/semconv/v1.10.0"
)

// gormOpen is like gorm.Open, but it uses otelsql to instrument the database.
func gormOpen(driverName, dataSourceName string, opts ...otelsql.Option) (*gorm.DB, error) {
	db, err := otelsql.Open(driverName, dataSourceName, opts...)
	if err != nil {
		return nil, err
	}
	return gorm.Open(driverName, db)
}

db, err := gormOpen("mysql", "user:password@/dbname",
    otelsql.WithAttributes(semconv.DBSystemMySQL))
if err != nil {
    panic(err)
}

To instrument GORM 2, use otelgorm.

Alternatives

• https://github.com/XSAM/otelsql - different driver registration and no metrics.
• https://github.com/j2gg0s/otsql - like XSAM/otelsql but with Prometheus metrics.

Documentation

Index

• func Open(driverName, dsn string, opts ...Option) (*sql.DB, error)
• func OpenDB(connector driver.Connector, opts ...Option) *sql.DB
• func ReportDBStatsMetrics(db *sql.DB, opts ...Option)
• func Version() string
• type Option
  • func WithAttributes(attrs ...attribute.KeyValue) Option
  • func WithDBName(name string) Option
  • func WithDBSystem(system string) Option
  • func WithMeterProvider(meterProvider metric.MeterProvider) Option
  • func WithQueryFormatter(queryFormatter func(query string) string) Option
  • func WithTracerProvider(tracerProvider trace.TracerProvider) Option

Functions

func Open

func Open(driverName, dsn string, opts ...Option) (*sql.DB, error)

Open is a wrapper over sql.Open that instruments the sql.DB to record executed queries using OpenTelemetry API.

func OpenDB

func OpenDB(connector driver.Connector, opts ...Option) *sql.DB

OpenDB is a wrapper over sql.OpenDB that instruments the sql.DB to record executed queries using OpenTelemetry API.

func ReportDBStatsMetrics

func ReportDBStatsMetrics(db *sql.DB, opts ...Option)

ReportDBStatsMetrics reports DBStats metrics using OpenTelemetry Metrics API.

func Version

func Version() string

Version is the current release version.

Types

type Option

type Option func(c *config)

func WithAttributes

func WithAttributes(attrs ...attribute.KeyValue) Option

WithAttributes configures attributes that are used to create a span.

func WithDBName

func WithDBName(name string) Option

WithDBName configures a db.name attribute.

func WithDBSystem

func WithDBSystem(system string) Option

WithDBSystem configures a db.system attribute. You should prefer using WithAttributes and semconv, for example, `otelsql.WithAttributes(semconv.DBSystemSqlite)`.

func WithMeterProvider

func WithMeterProvider(meterProvider metric.MeterProvider) Option

WithMeterProvider configures a metric.Meter used to create instruments.

func WithQueryFormatter

func WithQueryFormatter(queryFormatter func(query string) string) Option

WithQueryFormatter configures a query formatter

func WithTracerProvider

func WithTracerProvider(tracerProvider trace.TracerProvider) Option

WithTracerProvider configures a tracer provider that is used to create a tracer.