otelsql

https://github.com/xsam/otelsql
Admin
otelsql is an OpenTelemetry instrumentation for Go's `database/sql` package, designed to...
Tokens:38,435
Snippets:238
Trust Score:9.1
License:Apache-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install otelsql with go get

Source: https://github.com/xsam/otelsql/blob/main/README.md

Install the otelsql package using the go get command.

```bash
$ go get github.com/XSAM/otelsql
```

--------------------------------

### Register basic call example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Example showing how to register a wrapped driver and open a database connection using the generated name. Panics if registration or sql.Open fails.

```go
driverName, err := otelsql.Register("mysql")
if err != nil {
    panic(err)
}

db, err := sql.Open(driverName, mysqlDSN)
if err != nil {
    panic(err)
}
defer db.Close()
```

--------------------------------

### OpenDB basic call example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Example showing how to build a driver.Connector from a raw driver and pass it to otelsql.OpenDB with options. Panics if the driver does not implement driver.DriverContext or if OpenConnector fails.

```go
dctx, ok := rawDriver.(driver.DriverContext)
if !ok {
    panic("driver does not implement driver.DriverContext")
}
connector, err := dctx.OpenConnector(dsn)
if err != nil {
    panic(err)
}

db := otelsql.OpenDB(connector, otelsql.WithAttributes(semconv.DBSystemNameMySQL))
defer db.Close()
```

--------------------------------

### AttributesGetter usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/getters.md

Shows how to install a custom AttributesGetter via otelsql.WithAttributesGetter. The example adds an attribute with the argument count for statement executions, and returns nil otherwise.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithAttributesGetter(
    func(ctx context.Context, method otelsql.Method, query string, args []driver.NamedValue) []attribute.KeyValue {
        if method == otelsql.MethodStmtExec {
            return []attribute.KeyValue{attribute.Int("stmt.arg_count", len(args))}
        }
        return nil
    },
))
```

--------------------------------

### WithMeterProvider usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithMeterProvider when opening a database connection with otelsql.Open. It passes a custom meter provider 'mp' and panics on error.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithMeterProvider(mp))
if err != nil {
    panic(err)
}
```

--------------------------------

### WrapDriver basic call example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Shows how to wrap a raw driver with otelsql.WrapDriver, then use the returned driver.DriverContext to open a connector and create a *sql.DB. The example panics if the wrapped driver does not implement driver.DriverContext.

```go
otDriver := otelsql.WrapDriver(rawDriver)

dctx, ok := otDriver.(driver.DriverContext)
if !ok {
    panic("driver does not implement driver.DriverContext")
}
connector, err := dctx.OpenConnector(mysqlDSN)
if err != nil {
    panic(err)
}

db := sql.OpenDB(connector)
defer db.Close()
```

--------------------------------

### Example: Using WithDisableSkipErrMeasurement with otelsql.Open

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example usage of WithDisableSkipErrMeasurement in otelsql.Open. It also uses WithSpanOptions with DisableErrSkip to suppress driver.ErrSkip in spans.

```go
db, err := otelsql.Open("mysql", dsn,
    otelsql.WithDisableSkipErrMeasurement(true),
    otelsql.WithSpanOptions(otelsql.SpanOptions{DisableErrSkip: true}),
)
```

--------------------------------

### SpanNameFormatter usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/getters.md

Shows how to install a custom SpanNameFormatter via otelsql.WithSpanNameFormatter. The example prepends the method name with the first line of the query if the query is not empty.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithSpanNameFormatter(
    func(ctx context.Context, method otelsql.Method, query string) string {
        name := string(method)
        if query != "" {
            firstLine, _, _ := strings.Cut(query, "\n")
            return name + " " + firstLine
        }
        return name
    },
))
```

--------------------------------

### WithTracerProvider usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithTracerProvider when opening a database connection with otelsql.Open. It passes a custom tracer provider 'tp' and panics on error.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithTracerProvider(tp))
if err != nil {
    panic(err)
}
```

--------------------------------

### Print otelsql version with fmt.Println

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Example usage that prints the otelsql version string to standard output.

```go
fmt.Println("otelsql version:", otelsql.Version())
```

--------------------------------

### WithSpanOptions usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithSpanOptions to configure span behavior with specific SpanOptions fields enabled.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithSpanOptions(otelsql.SpanOptions{
    RowsNext:                true,
    DisableErrSkip:          true,
    OmitConnResetSession:    true,
    RowsChildOfQuery:        true,
}))
```

--------------------------------

### Bring up services with docker compose up -d

Source: https://github.com/xsam/otelsql/blob/main/example/stdout/README.md

Starts all services defined in the Docker Compose configuration. Requires Docker Compose V2.

```sh
docker compose up -d
```

--------------------------------

### WithAttributes usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithAttributes with otelsql.Open. It builds attributes from the DSN and adds a MySQL system attribute, then passes them to the option.

```go
attrs := append(otelsql.AttributesFromDSN(dsn), semconv.DBSystemNameMySQL)
db, err := otelsql.Open("mysql", dsn, otelsql.WithAttributes(attrs...))
```

--------------------------------

### SpanFilter usage example with WithSpanOptions

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/getters.md

Example showing how to use WithSpanOptions with a SpanFilter to skip tracing administrative SQL statements (those starting with 'SET ') while always tracing transaction methods. The filter returns true for all other queries.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithSpanOptions(otelsql.SpanOptions{
    SpanFilter: func(_ context.Context, method otelsql.Method, query string, _ []driver.NamedValue) bool {
        // Don't trace administrative SQL.
        if strings.HasPrefix(strings.ToUpper(strings.TrimSpace(query)), "SET ") {
            return false
        }
        // Always trace transactions.
        if method == otelsql.MethodConnBeginTx || method == otelsql.MethodTxCommit || method == otelsql.MethodTxRollback {
            return true
        }
        return true
    },
}))
```

--------------------------------

### Register multiple wrappers with different options

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Example showing how to register the same driver twice with different options (tracer and meter providers) and open separate database handles for each. The generated names are distinct.

```go
traceName, err := otelsql.Register("mysql", otelsql.WithTracerProvider(traceProvider))
if err != nil {
    panic(err)
}
metricsName, err := otelsql.Register("mysql", otelsql.WithMeterProvider(meterProvider))
if err != nil {
    panic(err)
}

dbTrace, _ := sql.Open(traceName, dsn)
dbMetrics, _ := sql.Open(metricsName, dsn)
```

--------------------------------

### Example — custom span names per method

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/methods-events.md

Shows how to use WithSpanNameFormatter to prefix span names with 'mysql.' for each method.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithSpanNameFormatter(
    func(_ context.Context, method otelsql.Method, _ string) string {
        return "mysql." + string(method)
    },
))

```

--------------------------------

### WithTextMapPropagator usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithTextMapPropagator with a TraceContext propagator to specify the propagator used by the SQLCommenter option.

```go
db, err := otelsql.Open("mysql", dsn,
    otelsql.WithSQLCommenter(true),
    otelsql.WithTextMapPropagator(propagation.TraceContext{}),
)
```

--------------------------------

### SQL commenter transformation example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example transformation showing how a SQL query is modified when SQL commenter is enabled. The comment is appended to the query.

```text
SELECT * from FOO
→ SELECT * from FOO /*traceparent='00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',tracestate='congo%3Dt61rcWkgMzE%2Crojo%3D00f067aa0ba902b7'*/
```

--------------------------------

### WithSQLCommenter usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithSQLCommenter with a composite text map propagator to enable SQL commenter and inject trace context and baggage into SQL comments.

```go
db, err := otelsql.Open("mysql", dsn,
    otelsql.WithSQLCommenter(true),
    otelsql.WithTextMapPropagator(propagation.NewCompositeTextMapPropagator(
        propagation.TraceContext{}, propagation.Baggage{},
    )),
)
```

--------------------------------

### Open database with fully configured otelsql options

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/configuration.md

Use this snippet to open a database connection with otelsql, configuring all available options including tracer and meter providers, span options, attribute getters, SQL commenter, and text map propagator. The example uses 'mysql' driver and a DSN variable; ensure the necessary providers and getters are defined. The library reads no environment variables; defaults come from OpenTelemetry globals.

```go
db, err := otelsql.Open("mysql", dsn,
	otelsql.WithTracerProvider(tp),
	otelsql.WithMeterProvider(mp),
	otelsql.WithAttributes(attrs...),
	otelsql.WithSpanNameFormatter(customFormatter),
	otelsql.WithSpanOptions(otelsql.SpanOptions{
		RowsNext:      true,
		OmitRows:      true,
		DisableErrSkip: true,
	}),
	otelsql.WithAttributesGetter(spanGetter),
	otelsql.WithInstrumentAttributesGetter(metricGetter),
	otelsql.WithSpanErrorAttributesGetter(spanErrGetter),
	otelsql.WithDisableSkipErrMeasurement(true),
	otelsql.WithSQLCommenter(true),
	otelsql.WithTextMapPropagator(propagation.TraceContext{}),
)
```

--------------------------------

### WithSpanNameFormatter usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithSpanNameFormatter to set a custom span name formatter that includes the method and query.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithSpanNameFormatter(
    func(_ context.Context, method otelsql.Method, query string) string {
        return fmt.Sprintf("%s: %s", method, query)
    },
))
```

--------------------------------

### Partial DSN (no port) example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/helpers.md

Shows the result when the DSN has no port: the whole string is used as host, and only server.address is returned.

```go
// "root:otel_password@db" -> server.address=db (split fails, whole string used as host, no port)
attrs := otelsql.AttributesFromDSN("root:otel_password@db")
// attrs == []attribute.KeyValue{semconv.ServerAddress("db")}
```

--------------------------------

### Instrument database/sql with otelsql.Open and RegisterDBStatsMetrics

Source: https://github.com/xsam/otelsql/blob/main/README.md

Shows how to open a database with otelsql.Open, passing attributes like semconv.DBSystemMySQL, and then register DB stats metrics with otelsql.RegisterDBStatsMetrics. The example panics on error and defers closing the database and unregistering the metrics.

```go
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()
}()
```

--------------------------------

### OpenDB

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Opens a database handle with OTel instrumentation, starting from a driver.Connector instead of a driver name. Returns an instrumented *sql.DB handle that cannot fail at creation time.

```APIDOC
## OpenDB

### Description
Opens a database handle with OTel instrumentation, starting from a `driver.Connector` instead of a driver name.

### Method
OpenDB

### Signature
`func OpenDB(c driver.Connector, options ...Option) *sql.DB`

### Parameters
- **c** (driver.Connector) - Required - Connector built from the raw driver (e.g. via `driver.DriverContext.OpenConnector`).
- **options** (Option) - Optional - Configuration options; see [configuration.md](../configuration.md).

### Return
An instrumented `*sql.DB` handle. Unlike `Open`, this cannot fail — the returned `*sql.DB` is created with `sql.OpenDB` and connection errors surface later, at query time.

### Throws
None (returns only a `*sql.DB`).

### Example — basic call
```go
dctx, ok := rawDriver.(driver.DriverContext)
if !ok {
    panic("driver does not implement driver.DriverContext")
}
connector, err := dctx.OpenConnector(dsn)
if err != nil {
    panic(err)
}

db := otelsql.OpenDB(connector, otelsql.WithAttributes(semconv.DBSystemNameMySQL))
defer db.Close()
```

Source: `sql.go:122-129`.
```

--------------------------------

### Example — matching on method values

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/methods-events.md

Shows a SpanFilter that matches on method values to trace transaction lifecycle, and references the MethodConnQuery and EventRowsNext constants.

```go
var _ otelsql.SpanFilter = func(ctx context.Context, method otelsql.Method, query string, args []driver.NamedValue) bool {
    switch method {
    case otelsql.MethodConnBeginTx, otelsql.MethodTxCommit, otelsql.MethodTxRollback:
        return true // trace transaction lifecycle
    default:
        return true
    }
}

var _ = otelsql.MethodConnQuery // "sql.conn.query"
var _ = otelsql.EventRowsNext   // "sql.rows.next"

```

--------------------------------

### Shut down services with docker compose down

Source: https://github.com/xsam/otelsql/blob/main/example/stdout/README.md

Stops and removes the services when finished with the example.

```sh
docker compose down
```

--------------------------------

### RegisterDBStatsMetrics basic call example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Registers sql.DBStats metrics for an instrumented *sql.DB using otelsql.RegisterDBStatsMetrics with the WithAttributes option. The returned metric.Registration must be unregistered when the database is no longer used.

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

--------------------------------

### Combining AttributesFromDSN with db.system.name

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/helpers.md

Shows the pattern used in examples to append a db.system.name attribute to the result of AttributesFromDSN.

```go
attrs := append(otelsql.AttributesFromDSN(mysqlDSN), semconv.DBSystemNameMySQL)
```

--------------------------------

### RegisterDBStatsMetrics error handling example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Shows error handling when registering db stats metrics. On failure, it logs a fatal error; otherwise it unregisters the registration on the shutdown path.

```go
reg, err := otelsql.RegisterDBStatsMetrics(db)
if err != nil {
    log.Fatalf("failed to register db stats metrics: %v", err)
}
// ... shutdown path
_ = reg.Unregister()
```

--------------------------------

### Example: WithInstrumentAttributesGetter usage

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/getters.md

Shows how to use otelsql.WithInstrumentAttributesGetter to add a custom attribute (db.operation.kind) to the duration measurement for every instrumented call.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithInstrumentAttributesGetter(
    func(ctx context.Context, method otelsql.Method, query string, args []driver.NamedValue) []attribute.KeyValue {
        return []attribute.KeyValue{attribute.String("db.operation.kind", string(method))}
    },
))
```

--------------------------------

### Basic call to AttributesFromDSN

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/helpers.md

Example of calling AttributesFromDSN with a full DSN and using the result with otelsql.Open. The DSN includes a protocol(addr) form with host and port.

```go
attrs := append(otelsql.AttributesFromDSN("root:pw@tcp(localhost:3306)/db?parseTime=true"),
    semconv.DBSystemNameMySQL)

db, err := otelsql.Open("mysql", dsn, otelsql.WithAttributes(attrs...))
if err != nil {
    panic(err)
}
```

--------------------------------

### Example: WithInstrumentErrorAttributesGetter usage

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/getters.md

Shows how to use otelsql.WithInstrumentErrorAttributesGetter to add an error message attribute when an operation returns an error.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithInstrumentErrorAttributesGetter(
    func(err error) []attribute.KeyValue {
        return []attribute.KeyValue{attribute.String("db.error.message", err.Error())}
    },
))
```

--------------------------------

### Basic otelsql.Open call

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Opens a MySQL database with instrumentation, adding a DB system attribute. Panics on error and defers closing the handle.

```go
db, err := otelsql.Open("mysql", "root:password@tcp(localhost:3306)/db", otelsql.WithAttributes(
    semconv.DBSystemNameMySQL,
))
if err != nil {
    panic(err)
}
defer db.Close()
```

--------------------------------

### Import otelsql package

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Import the otelsql package at the package root to access all entry point functions.

```go
import "github.com/XSAM/otelsql"
```

--------------------------------

### WithInstrumentAttributesGetter usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithInstrumentAttributesGetter to add a custom attribute (db.pool) to metric records. The callback is called on each metric record with (ctx, method, query, args).

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithInstrumentAttributesGetter(
    func(ctx context.Context, method otelsql.Method, query string, args []driver.NamedValue) []attribute.KeyValue {
        return []attribute.KeyValue{attribute.String("db.pool", "primary")}
    },
))
```

--------------------------------

### Open

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Opens a database handle with OTel instrumentation. It is a wrapper over sql.Open. Accepts a driver name and DSN, plus optional configuration options, and returns an instrumented *sql.DB handle.

```APIDOC
## Open

### Description
Opens a database handle with OTel instrumentation. It is a wrapper over `sql.Open`.

### Function Signature
`func Open(driverName, dataSourceName string, options ...Option) (*sql.DB, error)`

### Parameters
- **driverName** (string) - Required - Name of a driver previously registered with `database/sql` (e.g. `"mysql"`).
- **dataSourceName** (string) - Required - DSN passed to the driver; also used to bypass the driver's `Open` when the driver validates the DSN before opening connections.
- **options** (Option) - Optional - Configuration options; see configuration.md.

### Return
An instrumented `*sql.DB` handle. If the underlying driver implements `driver.DriverContext`, `Open` builds the wrapper through `driver.OpenConnector`; otherwise it falls back to a private `dsnConnector` that forwards to `driver.Driver.Open`.

### Throws
- error from `sql.Open` - Driver name is not registered or DSN is rejected
- error from `db.Close()` - Closing the probing handle fails
- error from `otDriver.OpenConnector` - The underlying `driver.DriverContext.OpenConnector` fails

### Notes
A probing `*sql.DB` is opened and closed immediately inside `Open` to fetch the driver instance; that handle is never used for queries. When the probe connects (drivers that do not implement `driver.DriverContext`), no connection leak occurs because the handle is closed right away.

### Example — basic call
```go
db, err := otelsql.Open("mysql", "root:password@tcp(localhost:3306)/db", otelsql.WithAttributes(
    semconv.DBSystemNameMySQL,
))
if err != nil {
    panic(err)
}
defer db.Close()
```

### Example — with error handling and DSN-derived attributes
```go
attrs := append(otelsql.AttributesFromDSN(dsn), semconv.DBSystemNameMySQL)

db, err := otelsql.Open("mysql", dsn, otelsql.WithAttributes(attrs...))
if err != nil {
    log.Fatalf("failed to open instrumented db: %v", err)
}
defer func() {
    _ = db.Close()
}()
```
```

--------------------------------

### WithAttributesGetter usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Example of using WithAttributesGetter to add a custom attribute (db.user.name) to spans. The callback is invoked once per span creation with (ctx, method, query, args).

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithAttributesGetter(
    func(ctx context.Context, method otelsql.Method, query string, args []driver.NamedValue) []attribute.KeyValue {
        return []attribute.KeyValue{semconv.DBUserName("app")}
    },
))
```

--------------------------------

### Basic otelsql.Open with SpanOptions

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/span-options.md

Opens a database connection with otelsql, configuring span options to enable ping, disable query spans, and omit rows. Panics if the connection fails.

```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithSpanOptions(otelsql.SpanOptions{
    Ping:          true,
    DisableQuery:  true,
    OmitRows:      true,
}))
if err != nil {
    panic(err)
}
```

--------------------------------

### SpanErrorAttributesGetter usage example

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/getters.md

Example from option.go:148-158 showing how to use WithSpanErrorAttributesGetter to add a DB response status code attribute for MySQL errors. It uses errors.As to check for *mysql.MySQLError and returns nil for other errors.

```go
otelsql.WithSpanErrorAttributesGetter(func(err error) []attribute.KeyValue {
    var mysqlErr *mysql.MySQLError
    if errors.As(err, &mysqlErr) {
        return []attribute.KeyValue{semconv.DBResponseStatusCode(strconv.Itoa(int(mysqlErr.Number)))}
    }
    return nil
})
```

--------------------------------

### newConfig function in config.go

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/configuration.md

Assembles the otelsql config from functional options, setting up tracer, meter, SQL commenter, and instruments. Uses default providers from the OpenTelemetry global if not overridden. Handles instrument creation errors via otel.Handle.

```go
func newConfig(options ...Option) config {
	cfg := config{
		TracerProvider:    otel.GetTracerProvider(),
		MeterProvider:     otel.GetMeterProvider(),
		SpanNameFormatter: defaultSpanNameFormatter,
	}
	for _, opt := range options {
		opt.Apply(&cfg)
	}

	cfg.Tracer = cfg.TracerProvider.Tracer(
		instrumentationName,                       // "github.com/XSAM/otelsql"
		trace.WithInstrumentationVersion(Version()),
	)
	cfg.Meter = cfg.MeterProvider.Meter(
		instrumentationName,
		metric.WithInstrumentationVersion(Version()),
	)

	cfg.SQLCommenter = newCommenter(cfg.SQLCommenterEnabled, cfg.TextMapPropagator)

	var err error
	if cfg.Instruments, err = newInstruments(cfg.Meter); err != nil {
		otel.Handle(err)
	}

	return cfg
}
```

--------------------------------

### otelsql.Open with error handling and DSN-derived attributes

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Opens a database with attributes derived from the DSN plus the DB system name. Uses log.Fatalf on error and ignores the close error.

```go
attrs := append(otelsql.AttributesFromDSN(dsn), semconv.DBSystemNameMySQL)

db, err := otelsql.Open("mysql", dsn, otelsql.WithAttributes(attrs...))
if err != nil {
    log.Fatalf("failed to open instrumented db: %v", err)
}
defer func() {
    _ = db.Close()
}()
```

--------------------------------

### Function signature: otelsql.Version()

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Declares the Version function with no parameters, returning a string. The current version is "0.44.0".

```go
func Version() string
```

--------------------------------

### Register

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Registers an OTel-wrapped driver with database/sql under a generated name and returns that name. The generated name is of the form `<driverName>-otelsql-<i>` where `<i>` is the first free integer slot in `0..999`.

```APIDOC
## Register

### Description
Registers an OTel-wrapped driver with `database/sql` under a generated name and returns that name.

### Method
Register

### Signature
`func Register(driverName string, options ...Option) (string, error)`

### Parameters
- **driverName** (string) - Required - Name of the already-registered driver to wrap.
- **options** (Option) - Optional - Configuration options; see [configuration.md](../configuration.md).

### Return
The generated driver name, of the form `<driverName>-otelsql-<i>` where `<i>` is the first free integer slot in `0..999` (driver name registration is scanned under `registerLock`). Pass the returned name to `sql.Open`. Because the returned name differs from `driverName`, the README recommends `Open`/`OpenDB` when client libraries depend on the original driver name.

### Throws
| Error | Condition |
|-------|-----------|
| error from `sql.Open` | The driver name is not registered |
| error from `db.Close()` | Closing the probing handle fails |
| `errors.New("unable to register driver, all slots have been taken")` | All 1000 generated slots (`maxDriverSlot`) are already in use (`sql.go:76-77`) |

### Example — basic call
```go
driverName, err := otelsql.Register("mysql")
if err != nil {
    panic(err)
}

db, err := sql.Open(driverName, mysqlDSN)
if err != nil {
    panic(err)
}
defer db.Close()
```

### Example — multiple wrappers with different options
```go
traceName, err := otelsql.Register("mysql", otelsql.WithTracerProvider(traceProvider))
if err != nil {
    panic(err)
}
metricsName, err := otelsql.Register("mysql", otelsql.WithMeterProvider(meterProvider))
if err != nil {
    panic(err)
}

dbTrace, _ := sql.Open(traceName, dsn)
dbMetrics, _ := sql.Open(metricsName, dsn)
```

Source: `sql.go:39-80`.
```

--------------------------------

### Check client logs with docker compose logs client

Source: https://github.com/xsam/otelsql/blob/main/example/stdout/README.md

Displays the logs of the 'client' service to see the trace data and metrics output.

```sh
docker compose logs client
```

--------------------------------

### Advanced SpanOptions with filtering and selective recording

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/span-options.md

Configures SpanOptions to omit housekeeping spans, skip recording connection errors, track row iteration as child spans, and filter out admin queries starting with 'SET '. The SpanFilter type is defined in config.go:51.

```go
otelsql.WithSpanOptions(otelsql.SpanOptions{
    // Only create spans for queries and statements, never for housekeeping.
    OmitConnResetSession: true,
    OmitConnPrepare:      true,
    OmitConnectorConnect: true,

    // Only record errors once per unique error type.
    RecordError: func(err error) bool {
        return err != driver.ErrBadConn // connection errors are expected; skip them
    },

    // Track row iteration as child spans of the query span.
    RowsNext:         true,
    RowsChildOfQuery: true,

    // Skip spans for admin queries (the SpanFilter type is defined in config.go:51).
    SpanFilter: func(_ context.Context, method otelsql.Method, query string, _ []driver.NamedValue) bool {
        return !strings.HasPrefix(strings.TrimSpace(query), "SET ")
    },
})
```

--------------------------------

### WrapDriver

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Wraps a raw driver.Driver with OTel instrumentation and returns an instrumented driver. The returned driver preserves driver.DriverContext support if the input implements it.

```APIDOC
## WrapDriver

### Description
Wraps a raw `driver.Driver` with OTel instrumentation and returns an instrumented driver. If the input implements `driver.DriverContext`, the returned value also implements `driver.DriverContext` (so `OpenConnector` keeps working). If the input only implements `driver.Driver`, the returned value is an anonymous struct embedding the wrapped driver, so it does *not* needlessly satisfy `driver.DriverContext`.

### Method
Function

### Signature
```go
func WrapDriver(dri driver.Driver, options ...Option) driver.Driver
```

### Parameters
- **dri** (driver.Driver) - Required - The driver instance to wrap.
- **options** (Option) - Optional - Configuration options; see [configuration.md](../configuration.md).

### Return
- **driver.Driver** - The instrumented driver.

### Throws
None.

### Example — basic call
```go
otDriver := otelsql.WrapDriver(rawDriver)

dctx, ok := otDriver.(driver.DriverContext)
if !ok {
    panic("driver does not implement driver.DriverContext")
}
connector, err := dctx.OpenConnector(mysqlDSN)
if err != nil {
    panic(err)
}

db := sql.OpenDB(connector)
defer db.Close()
```

### Source
`sql.go:82-85`, `driver.go:14-24`.
```

--------------------------------

### Register function signature

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Signature for the Register function, which wraps an already-registered driver and returns a generated driver name of the form <driverName>-otelsql-<i>. The returned name must be passed to sql.Open.

```go
func Register(driverName string, options ...Option) (string, error)
```

--------------------------------

### func Version() string

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Returns the current release version of otelsql as a string. This function takes no parameters and returns the module version string, which is also used internally as the instrumentation version for tracer and meter creation.

```APIDOC
## func Version() string

### Description
Returns the current release version of otelsql in use.

### Method
Function call

### Endpoint
N/A (Go function)

### Parameters
None.

### Return
- **string** - The module version string, currently `"0.44.0"`. Also used internally as the instrumentation version for tracer and meter creation.

### Example
```go
fmt.Println("otelsql version:", otelsql.Version())
```

### Source
`version.go:18-20`
```

--------------------------------

### WithSpanOptions

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Sets the span options.

```APIDOC
## WithSpanOptions

### Description
Sets the span options.

### Signature
```go
func WithSpanOptions(opts SpanOptions) Option
```

### Parameters
- `opts` (SpanOptions) - Required - The span options to use.

### Applies to
`cfg.SpanOptions`
```

--------------------------------

### WithMeterProvider

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Specifies the meter provider used to create a meter. If not specified, the global provider is used.

```APIDOC
## WithMeterProvider

### Description
Specifies the meter provider used to create a meter. If not specified, the global provider is used.

### Function Signature
```go
func WithMeterProvider(provider metric.MeterProvider) Option
```

### Parameters
- **provider** (metric.MeterProvider) - Required - Provider for the meter used for all metric instruments (operation duration + DB stats). Default: global provider (`otel.GetMeterProvider()`).

### Example
```go
db, err := otelsql.Open("mysql", dsn, otelsql.WithMeterProvider(mp))
if err != nil {
    panic(err)
}
```

### Source
`option.go:73-78`
```

--------------------------------

### Option interface definition

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/types.md

Defines the Option interface with an Apply method that sets a configuration value. Accepted by Register, WrapDriver, Open, OpenDB, and RegisterDBStatsMetrics. The concrete config passed to Apply is the unexported config struct.

```go
// Option is the interface that applies a configuration option.
type Option interface {
	// Apply sets the Option value of a config.
	Apply(cfg *config)
}
```

--------------------------------

### Open function signature

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/entry-points.md

Signature of the Open function, which opens a database handle with OTel instrumentation. It wraps sql.Open and accepts driver name, data source name, and optional options.

```go
func Open(driverName, dataSourceName string, options ...Option) (*sql.DB, error)
```

--------------------------------

### WithDisableSkipErrMeasurement function signature

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Function signature for WithDisableSkipErrMeasurement. It takes a boolean parameter and returns an Option.

```go
func WithDisableSkipErrMeasurement(disable bool) Option
```

--------------------------------

### WithAttributes

Source: https://github.com/xsam/otelsql/blob/main/_autodocs/api-reference/options.md

Appends attributes to the configuration.

```APIDOC
## WithAttributes

### Description
Appends attributes to the configuration.

### Signature
```go
func WithAttributes(attributes ...attribute.KeyValue) Option
```

### Parameters
- `attributes` (attribute.KeyValue) - Required - The attributes to append.

### Applies to
appends `cfg.Attributes`
```
Tokens:
Raw