go-sql-driver / mysql / 23700483573

83%

master: 83%

Pull #1753

github

# feat: add QueryTracer interface for SQL statement tracing (#1716)

## Summary

Add a `QueryTracer` interface that allows users to trace SQL query execution for logging, metrics, or distributed tracing. This feature is inspired by the pgx driver's tracelog implementation.

## Motivation

Applications often need visibility into database query execution for:

- **Debugging**: Log slow queries and identify bottlenecks
- **Metrics**: Track query execution times, error rates, and throughput
- **Distributed Tracing**: Integrate with observability tools (OpenTelemetry, Jaeger, etc.) using context propagation
- **Compliance**: Audit logging for data access

## Implementation

### New Interface (tracer.go)

Defines the `QueryTracer` interface with two methods:

```go
type QueryTracer interface {
    TraceQueryStart(ctx context.Context, query string, args []driver.NamedValue) context.Context
    TraceQueryEnd(ctx context.Context, err error, duration time.Duration)
}
```

- `TraceQueryStart` is called before query execution with the query string and arguments, returning a context for span propagation
- `TraceQueryEnd` is called after query completion with the error and wall-clock duration

The `mysqlConn.traceQuery()` helper wraps query execution with automatic tracing. When no tracer is configured, overhead is a single nil check per query.

### Configuration (dsn.go)

- Added `tracer QueryTracer` field to `Config` struct
- Added `WithTracer(tracer QueryTracer)` functional option

### Instrumented Paths (connection.go, statement.go)

- `ExecContext`
- `QueryContext`
- `PrepareContext`
- `mysqlStmt.ExecContext`
- `mysqlStmt.QueryContext`

## Usage Example

```go
package main

import (
    "context"
    "database/sql"
    "fmt"
    "github.com/go-sql-driver/mysql"
)

type DebugTracer struct{}

func (t *DebugTracer) TraceQueryStart(ctx context.Context, query string, args []driver.NamedValue) context.Context {
    fmt.Printf("[QUERY START] %s | args: %v\n", query, ... (continued)

31 of 31 new or added lines in 3 files covered. (100.0%)

3345 of 4048 relevant lines covered (82.63%)

2384163.2 hits per line