otelsql Documentation

When database operations fail, otelsql automatically populates the error.type attribute to assist in debugging. The attribution logic follows these rules:

1. Standard driver errors: Specific handling for database/sql/driver.ErrBadConn, database/sql/driver.ErrSkip, and database/sql/driver.ErrRemoveArgument.
2. Custom errors: Uses the fully qualified type name (e.g., github.com/your/package.CustomError).
3. Built-in errors: Uses the type name (e.g., *errors.errorString for errors created via errors.New()).

Once the Docker Compose services are running and the client service has finished its execution, you can view the instrumentation results at the following endpoints:

• Jaeger UI (Traces): http://localhost:16686
• Prometheus UI (Metrics): http://localhost:9090

To add OpenTelemetry instrumentation for Golang database/sql to your project, install the otelsql module using go get.

$ go get github.com/XSAM/otelsql

The otelsql package provides four ways to instrument database/sql: otelsql.Open, otelsql.OpenDB, otelsql.Register, and otelsql.WrapDriver.

To instrument a database and collect connection statistics metrics (from Go's sql.DBStats), use otelsql.Open followed by otelsql.RegisterDBStatsMetrics. You can pass otelsql.WithAttributes to include semantic conventions like semconv.DBSystemMySQL.

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

reg, err := otelsql.RegisterDBStatsMetrics(db, otelsql.WithAttributes(
	semconv.DBSystemMySQL,
))
if err != nil {
	panic(err)
}
defer func() {
	_ = db.Close()
	_ = reg.Unregister()
}()

This example demonstrates a MySQL client using database/sql with instrumentation. The client prints trace data to stdout and serves metrics data via a Prometheus client.

To run the full environment, ensure you have Docker Compose V2 installed, then follow these steps:

1. Start the services: Run the following command to bring up all necessary services (MySQL, client, etc.) in detached mode.
2. Verify results: Check the logs of the client service to observe the instrumented trace data being printed to stdout.
3. Cleanup: Shut down the services when finished.

# Start the services
docker compose up -d

# Check the client logs for trace data
docker compose logs client

# Shut down the services
docker compose down

This example demonstrates a MySQL client using database/sql with otelsql instrumentation. It shows how to export trace data to Jaeger and metrics data to Prometheus via an OpenTelemetry Collector.

To run the full stack (MySQL, OpenTelemetry Collector, Jaeger, Prometheus, and the instrumented client), use Docker Compose.

Prerequisites:

• Docker Compose V2 installed.

Workflow:

1. Start the services.
2. Monitor the client service logs to ensure the workload completes.
3. Access the visualization UIs to inspect traces and metrics.
4. Shut down the environment.

# Start all services in the background
docker compose up -d

# Monitor the client logs to ensure the example execution finishes
docker compose logs client

# Shut down the services when finished
docker compose down

SQLCommenter allows injecting trace context into SQL statements as comments, enabling distributed tracing across database boundaries.

To use it, you must enable it via WithSQLCommenter(true). You can also specify a custom propagator using WithTextMapPropagator(propagator). If no propagator is provided, the global text map propagator is used.

Warning: These options are EXPERIMENTAL and may change or be removed in future releases.

Example transformation: SELECT * from FOO becomes SELECT * from FOO /*traceparent='...',tracestate='...'*/

// Enable SQLCommenter with a custom propagator
otelsql.WithSQLCommenter(true),
otelsql.WithTextMapPropagator(myPropagator),

The otConnector is an internal implementation of the driver.Connector and io.Closer interfaces. It acts as a middleware layer that wraps an existing driver.Connector.

When Connect(ctx) is called on an otConnector:

1. It records metrics for the connection attempt.
2. It optionally creates an OpenTelemetry span if SpanOptions.OmitConnectorConnect is false and the method passes the configured filters.
3. It delegates the actual connection to the underlying driver.Connector.
4. It wraps the resulting driver.Conn into an instrumented connection via newConn.

This allows otelsql to intercept the connection lifecycle to provide observability (traces and metrics) without modifying the underlying database driver.

The example/otel-collector/docker-compose.yaml file provides a complete environment to demonstrate otelsql instrumentation. It orchestrates a MySQL database, an OpenTelemetry Collector, Prometheus for metrics, Jaeger for traces, and a sample client application.

To use this setup, ensure you have the following files in the same directory as the docker-compose.yaml:

• otel-collector.yaml: Configuration for the OpenTelemetry Collector.
• prometheus.yaml: Configuration for Prometheus.
• Dockerfile: The build context for the client service (located at the repository root via ../..).

# Run the stack using docker-compose
docker-compose up