Skip to content
This repository has been archived by the owner on May 12, 2023. It is now read-only.
/ otelsql Public archive
forked from XSAM/otelsql

OpenTelemetry instrumentation for database/sql

License

Notifications You must be signed in to change notification settings

rekki/otelsql

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

otelsql

ci codecov Go Report Card Documentation

It is an OpenTelemetry instrumentation for Golang database/sql, a port from open-telemetry/opentelemetry-go-contrib#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 and a docker-compose example for details.

Trace Instruments

It creates spans on corresponding methods.

Use SpanOptions to adjust creation of spans.

Metric Instruments

Name Description Units Instrument Type Value Type Attribute Key(s) Attribute Values
db.sql.latency The latency of calls in milliseconds ms Histogram float64 status ok, error
method method name, like sql.conn.query
db.sql.connection.max_open Maximum number of open connections to the database Asynchronous Gauge int64
db.sql.connection.open The number of established connections both in use and idle Asynchronous Gauge int64 status idle, inuse
db.sql.connection.wait The total number of connections waited for Asynchronous Counter int64
db.sql.connection.wait_duration The total time blocked waiting for a new connection ms Asynchronous Counter float64
db.sql.connection.closed_max_idle The total number of connections closed due to SetMaxIdleConns Asynchronous Counter int64
db.sql.connection.closed_max_idle_time The total number of connections closed due to SetConnMaxIdleTime Asynchronous Counter int64
db.sql.connection.closed_max_lifetime The total number of connections closed due to SetConnMaxLifetime Asynchronous Counter int64

Compatibility

This project is tested on the following systems.

OS Go Version Architecture
Ubuntu 1.20 amd64
Ubuntu 1.19 amd64
Ubuntu 1.18 amd64
Ubuntu 1.20 386
Ubuntu 1.19 386
Ubuntu 1.18 386
MacOS 1.20 amd64
MacOS 1.19 amd64
MacOS 1.18 amd64
Windows 1.20 amd64
Windows 1.19 amd64
Windows 1.18 amd64
Windows 1.20 386
Windows 1.19 386
Windows 1.18 386

While this project should work for other systems, no compatibility guarantees are made for those systems currently.

The project follows the Release Policy to support major Go releases.

Why port this?

Based on this comment, OpenTelemetry SIG team like to see broader usage and community consensus on an approach before they commit to the level of support that would be required of a package in contrib. But it is painful for users without a stable version, and they have to use replacement in go.mod to use this instrumentation.

Therefore, I host this module independently for convenience and make improvements based on users' feedback.

Communication

I use GitHub discussions/issues for most communications. Feel free to contact me on CNCF slack.

About

OpenTelemetry instrumentation for database/sql

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Go 93.6%
  • Makefile 3.9%
  • Shell 1.9%
  • Dockerfile 0.6%