otelsql

package module
v0.40.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 8, 2025 License: Apache-2.0 Imports: 20 Imported by: 178

README ΒΆ

otelsql

ci codecov Go Report Card Documentation

It is an OpenTelemetry instrumentation for Golang database/sql, a port from https://github.com/open-telemetry/opentelemetry-go-contrib/pull/505.

It instruments traces and metrics.

Install

$ go get github.com/XSAM/otelsql

Usage

This project provides four different ways to instrument database/sql:

otelsql.Open, otelsql.OpenDB, otesql.Register and otelsql.WrapDriver.

And then use otelsql.RegisterDBStatsMetrics to instrument sql.DBStats with metrics.

db, err := otelsql.Open("mysql", mysqlDSN, otelsql.WithAttributes(
	semconv.DBSystemMySQL,
))
if err != nil {
	panic(err)
}
defer db.Close()

err = otelsql.RegisterDBStatsMetrics(db, otelsql.WithAttributes(
	semconv.DBSystemMySQL,
))
if err != nil {
	panic(err)
}

Check Option for more features like adding context propagation to SQL queries when enabling WithSQLCommenter.

See godoc for details.

Blog

Getting started with otelsql, the OpenTelemetry instrumentation for Go SQL, is a blog post that explains how to use otelsql in miutes.

Examples

This project provides two docker-compose examples to show how to use it.

  • The stdout example is a simple example to show how to use it with a MySQL database. It prints the trace data to stdout and serves metrics data via prometheus client.
  • The otel-collector example is a more complex example to show how to use it with a MySQL database and an OpenTelemetry Collector. It sends the trace data and metrics data to an OpenTelemetry Collector. Then, it shows data visually on Jaeger and Prometheus servers.

Semantic Convention Stability Migration

The environment variable OTEL_SEMCONV_STABILITY_OPT_IN will be supported for at least six months. After this period, support for legacy metrics and Semantic Conventions v1.24.0 may be removed in the next release.

Check the CHANGELOG.md for more details.

Trace Instruments

It creates spans on corresponding methods.

Use SpanOptions to adjust creation of spans.

Trace Semantic Convention Stability

The instrumentation supports different OpenTelemetry semantic convention stability levels, configured through the OTEL_SEMCONV_STABILITY_OPT_IN environment variable:

Setting Description
empty (default) Only uses db.statement attribute.
database/dup Uses both db.statement and db.query.text attributes.
database Uses db.query.text attribute.

Metric Instruments

Two types of metrics are provided depending on the semantic convention stability setting:

Legacy Metrics (default)
  • db.sql.latency: The latency of calls in milliseconds
    • Unit: milliseconds
    • Attributes: method (method name), status (ok, error)
OpenTelemetry Semantic Convention Metrics