otelgorm

README

GORM OpenTelemetry instrumentation

OpenTelemetry GORM instrumentation records database queries and reports DBStats metrics.

Installation

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

Usage

To instrument GORM, you need to install the plugin provided by otelgorm:

import (
	"github.com/uptrace/opentelemetry-go-extra/otelgorm"
	"gorm.io/driver/sqlite"
	"gorm.io/gorm"
)

db, err := gorm.Open(sqlite.Open("file::memory:?cache=shared"), &gorm.Config{})
if err != nil {
	panic(err)
}

if err := db.Use(otelgorm.NewPlugin()); err != nil {
	panic(err)
}

And then use db.WithContext(ctx) to propagate the active span via context:

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

See example for details.

Options

You can customize the plugin using configuration options:

• WithAttributes configures attributes that are used to create a span.
• WithDBName configures a db.name attribute.

For example:

otelPlugin := otelgorm.NewPlugin(otelgorm.WithDBName("mydb"))

if err := db.Use(otelPlugin); err != nil {
	panic(err)
}

Documentation

Index

• func NewPlugin(opts ...Option) gorm.Plugin
• func Version() string
• type Option
  • func WithAttributes(attrs ...attribute.KeyValue) Option
  • func WithDBName(name string) Option
  • func WithDryRunTx() Option
  • func WithQueryFormatter(queryFormatter func(query string) string) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
  • func WithoutMetrics() Option
  • func WithoutQueryVariables() Option

Functions

func NewPlugin

func NewPlugin(opts ...Option) gorm.Plugin

func Version

func Version() string

Version is the current release version.

Types

type Option

type Option func(p *otelPlugin)

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 WithDryRunTx

func WithDryRunTx() Option

WithDryRunTx will add trace spans for "dry run" callback invocations from Gorm. "Dry Run" invocations occur when Gorm is just rendering SQL, but not actually executing it against a database.

func WithQueryFormatter

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

WithQueryFormatter configures a query formatter

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

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

func WithoutMetrics

func WithoutMetrics() Option

WithoutMetrics prevents DBStats metrics from being reported.

func WithoutQueryVariables

func WithoutQueryVariables() Option

WithoutQueryVariables configures the db.statement attribute to exclude query variables