firebirdotel

README

firebirdsql-otel

OpenTelemetry instrumentation helpers for the Go Firebird driver github.com/nakagami/firebirdsql.

This package gives Firebird applications the same ergonomic shape that many PostgreSQL projects use: open an instrumented *sql.DB once, then normal ExecContext, QueryContext, PrepareContext, transactions, and procedure calls produce spans automatically.

Install

go get github.com/Makarechi/firebirdsql-otel

Usage

package main

import (
	"context"
	"log"

	firebirdotel "github.com/Makarechi/firebirdsql-otel"
)

func main() {
	ctx := context.Background()
	dsn := "sysdba:masterkey@localhost:3050/var/lib/firebird/app.fdb"

	db, err := firebirdotel.Open(dsn)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	_, err = db.ExecContext(ctx, "execute procedure recalculate_invoice(?)", 42)
	if err != nil {
		log.Fatal(err)
	}
}

If your framework needs a driver name instead of a ready *sql.DB:

driverName, err := firebirdotel.Register()
if err != nil {
	log.Fatal(err)
}

db, err := sql.Open(driverName, dsn)

Metrics

Operation duration metrics are emitted through otelsql. You can also register standard database/sql pool statistics:

reg, err := firebirdotel.RegisterDBStatsMetrics(db, dsn)
if err != nil {
	log.Fatal(err)
}
defer reg.Unregister()

Pass custom OpenTelemetry providers when your application does not use the global providers:

db, err := firebirdotel.Open(
	dsn,
	firebirdotel.WithTracerProvider(tracerProvider),
	firebirdotel.WithMeterProvider(meterProvider),
)

What You See

For a stored procedure call from Go, for example:

execute procedure recalculate_invoice(?)

the trace shows the Go application calling Firebird, the elapsed time, the SQL text when enabled by semantic-convention settings, and any returned error.

The instrumentation does not inspect work inside the Firebird engine. It will not automatically show which tables, indexes, triggers, or nested procedures were used inside the stored procedure. That level of detail needs Firebird server-side tracing or a separate integration with Firebird Trace API output.

Firebird Service API

The main SQL path is covered by database/sql instrumentation. Firebird-specific administrative APIs such as backup, nbackup, maintenance, user management, trace sessions, and events are not SQL queries. They use the Firebird Services API or event protocol, so they need separate wrappers if you want spans around those operations.

This repository is structured so those wrappers can be added without changing the SQL instrumentation API.

Development

Run tests:

go test ./...

The tests use an in-memory mock SQL driver and do not require a running Firebird server.

Documentation

Overview

Package firebirdotel provides OpenTelemetry instrumentation helpers for the github.com/nakagami/firebirdsql database/sql driver.

Index

• Constants
• func AttributesFromDSN(dsn string) []attribute.KeyValue
• func DefaultAttributes(dsn string) []attribute.KeyValue
• func Open(dsn string, options ...Option) (*sql.DB, error)
• func OpenCreateDB(dsn string, options ...Option) (*sql.DB, error)
• func OpenDB(connector driver.Connector, options ...Option) *sql.DB
• func OpenDBWithDSN(connector driver.Connector, dsn string, options ...Option) *sql.DB
• func OpenWithDriver(driverName, dsn string, options ...Option) (*sql.DB, error)
• func Register(options ...Option) (string, error)
• func RegisterCreateDB(options ...Option) (string, error)
• func RegisterDBStatsMetrics(db *sql.DB, dsn string, options ...Option) (metric.Registration, error)
• func RegisterWithDriver(driverName, dsn string, options ...Option) (string, error)
• type AttributesGetter
• type InstrumentAttributesGetter
• type InstrumentErrorAttributesGetter
• type Method
• type Option
  • func WithAttributes(attributes ...attribute.KeyValue) Option
  • func WithAttributesGetter(getter AttributesGetter) Option
  • func WithDefaultAttributes(dsn string) Option
  • func WithInstrumentAttributesGetter(getter InstrumentAttributesGetter) Option
  • func WithInstrumentErrorAttributesGetter(getter InstrumentErrorAttributesGetter) Option
  • func WithMeterProvider(provider metric.MeterProvider) Option
  • func WithSQLCommenter(enabled bool) Option
  • func WithSpanNameFormatter(formatter SpanNameFormatter) Option
  • func WithSpanOptions(options SpanOptions) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
• type SpanNameFormatter
• type SpanOptions

Constants

const (
	// DriverName is the standard driver name registered by github.com/nakagami/firebirdsql.
	DriverName = "firebirdsql"

	// CreateDBDriverName is the create-database driver name registered by github.com/nakagami/firebirdsql.
	CreateDBDriverName = "firebirdsql_createdb"
)

Functions

func AttributesFromDSN

func AttributesFromDSN(dsn string) []attribute.KeyValue

AttributesFromDSN returns best-effort network attributes parsed from dsn.

func DefaultAttributes

func DefaultAttributes(dsn string) []attribute.KeyValue

DefaultAttributes returns Firebird database semantic attributes plus best-effort network attributes parsed from dsn.

func Open

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

Open opens an instrumented Firebird database handle.

func OpenCreateDB

func OpenCreateDB(dsn string, options ...Option) (*sql.DB, error)

OpenCreateDB opens an instrumented Firebird create-database handle.

func OpenDB

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

OpenDB wraps a driver connector in OpenTelemetry instrumentation.

func OpenDBWithDSN

func OpenDBWithDSN(connector driver.Connector, dsn string, options ...Option) *sql.DB

OpenDBWithDSN wraps a driver connector and also derives network attributes from dsn.

func OpenWithDriver

func OpenWithDriver(driverName, dsn string, options ...Option) (*sql.DB, error)

OpenWithDriver opens an instrumented database handle using a registered driver.

This is useful for tests and for applications that register a custom Firebird driver name.

func Register

func Register(options ...Option) (string, error)

Register registers an instrumented wrapper around the Firebird driver and returns the generated driver name.

Prefer Open when each sql.DB handle has a known DSN. Register is useful for frameworks that need a driver name before calling sql.Open themselves.

func RegisterCreateDB

func RegisterCreateDB(options ...Option) (string, error)

RegisterCreateDB registers an instrumented wrapper around the create-database driver.

func RegisterDBStatsMetrics

func RegisterDBStatsMetrics(db *sql.DB, dsn string, options ...Option) (metric.Registration, error)

RegisterDBStatsMetrics registers database/sql pool statistics metrics for db.

func RegisterWithDriver

func RegisterWithDriver(driverName, dsn string, options ...Option) (string, error)

RegisterWithDriver registers an instrumented wrapper around driverName.

Types

type AttributesGetter

type AttributesGetter = otelsql.AttributesGetter

AttributesGetter returns span attributes for a database/sql operation.

type InstrumentAttributesGetter

type InstrumentAttributesGetter = otelsql.InstrumentAttributesGetter

InstrumentAttributesGetter returns metric attributes for a successful operation.

type InstrumentErrorAttributesGetter

type InstrumentErrorAttributesGetter = otelsql.InstrumentErrorAttributesGetter

InstrumentErrorAttributesGetter returns metric attributes for a failed operation.

type Method

type Method = otelsql.Method

Method is the database/sql operation name passed to span name formatters.

type Option

type Option = otelsql.Option

Option configures OpenTelemetry behavior.

func WithAttributes

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

WithAttributes adds static attributes to spans and metrics.

func WithAttributesGetter

func WithAttributesGetter(getter AttributesGetter) Option

WithAttributesGetter configures per-operation span attributes.

func WithDefaultAttributes

func WithDefaultAttributes(dsn string) Option

WithDefaultAttributes adds Firebird database semantic attributes and best-effort network attributes parsed from dsn.

func WithInstrumentAttributesGetter

func WithInstrumentAttributesGetter(getter InstrumentAttributesGetter) Option

WithInstrumentAttributesGetter configures per-operation metric attributes.

func WithInstrumentErrorAttributesGetter

func WithInstrumentErrorAttributesGetter(getter InstrumentErrorAttributesGetter) Option

WithInstrumentErrorAttributesGetter configures per-operation metric error attributes.

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider configures the meter provider used by metrics.

func WithSQLCommenter

func WithSQLCommenter(enabled bool) Option

WithSQLCommenter enables SQLCommenter trace context injection.

func WithSpanNameFormatter

func WithSpanNameFormatter(formatter SpanNameFormatter) Option

WithSpanNameFormatter configures span names.

func WithSpanOptions

func WithSpanOptions(options SpanOptions) Option

WithSpanOptions configures which database/sql operations create spans.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider configures the tracer provider used by spans.

type SpanNameFormatter

type SpanNameFormatter = otelsql.SpanNameFormatter

SpanNameFormatter formats span names.

type SpanOptions

type SpanOptions = otelsql.SpanOptions

SpanOptions controls which database/sql operations create spans.