1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
[](https://pkg.go.dev/github.com/uptrace/opentelemetry-go-extra/otelsql)
# database/sql instrumentation for OpenTelemetry Go
[database/sql OpenTelemetry instrumentation](https://uptrace.dev/getinstrument/opentelemetry-database-sql.html)
records database queries (including `Tx` and `Stmt` queries) and reports `DBStats` metrics.
## Installation
```shell
go get github.com/uptrace/opentelemetry-go-extra/otelsql
```
## Usage
To instrument database/sql, you need to connect to a database using the API provided by otelsql:
| sql | otelsql |
| --------------------------- | ------------------------------- |
| `sql.Open(driverName, dsn)` | `otelsql.Open(driverName, dsn)` |
| `sql.OpenDB(connector)` | `otelsql.OpenDB(connector)` |
```go
import (
"github.com/uptrace/opentelemetry-go-extra/otelsql"
semconv "go.opentelemetry.io/otel/semconv/v1.10.0"
)
db, err := otelsql.Open("sqlite", "file::memory:?cache=shared",
otelsql.WithAttributes(semconv.DBSystemSqlite),
otelsql.WithDBName("mydb"))
if err != nil {
panic(err)
}
// db is *sql.DB
```
And then use context-aware API to propagate the active span via
[context](https://uptrace.dev/opentelemetry/go-tracing.html#context):
```go
var num int
if err := db.QueryRowContext(ctx, "SELECT 42").Scan(&num); err != nil {
panic(err)
}
```
See [example](/example/) for details.
## Options
Both [otelsql.Open](https://pkg.go.dev/github.com/uptrace/opentelemetry-go-extra/otelsql#Open) and
[otelsql.OpenDB](https://pkg.go.dev/github.com/uptrace/opentelemetry-go-extra/otelsql#OpenDB) accept
the same [options](https://pkg.go.dev/github.com/uptrace/opentelemetry-go-extra/otelsql#Option):
- [WithAttributes](https://pkg.go.dev/github.com/uptrace/opentelemetry-go-extra/otelsql#WithAttributes)
configures attributes that are used to create a span.
- [WithDBName](https://pkg.go.dev/github.com/uptrace/opentelemetry-go-extra/otelsql#WithDBName)
configures a `db.name` attribute.
- [WithDBSystem](https://pkg.go.dev/github.com/uptrace/opentelemetry-go-extra/otelsql#WithDBSystem)
configures a `db.system` attribute. When possible, you should prefer using WithAttributes and
[semconv](https://pkg.go.dev/go.opentelemetry.io/otel/semconv/v1.10.0), for example,
`otelsql.WithAttributes(semconv.DBSystemSqlite)`.
## sqlboiler
You can use otelsql to instrument [sqlboiler](https://github.com/volatiletech/sqlboiler) ORM:
```go
import (
"github.com/uptrace/opentelemetry-go-extra/otelsql"
semconv "go.opentelemetry.io/otel/semconv/v1.10.0"
)
db, err := otelsql.Open("postgres", "dbname=fun user=abc",
otelsql.WithAttributes(semconv.DBSystemPostgreSQL))
if err != nil {
return err
}
boil.SetDB(db)
```
## GORM 1
You can use otelsql to instrument [GORM 1](https://v1.gorm.io/):
```go
import (
"github.com/jinzhu/gorm"
"github.com/uptrace/opentelemetry-go-extra/otelsql"
semconv "go.opentelemetry.io/otel/semconv/v1.10.0"
)
// gormOpen is like gorm.Open, but it uses otelsql to instrument the database.
func gormOpen(driverName, dataSourceName string, opts ...otelsql.Option) (*gorm.DB, error) {
db, err := otelsql.Open(driverName, dataSourceName, opts...)
if err != nil {
return nil, err
}
return gorm.Open(driverName, db)
}
db, err := gormOpen("mysql", "user:password@/dbname",
otelsql.WithAttributes(semconv.DBSystemMySQL))
if err != nil {
panic(err)
}
```
To instrument GORM 2, use
[otelgorm](https://github.com/uptrace/opentelemetry-go-extra/tree/main/otelgorm).
## Alternatives
- https://github.com/XSAM/otelsql - different driver registration and no metrics.
- https://github.com/j2gg0s/otsql - like XSAM/otelsql but with Prometheus metrics.
|
