gtsocial-umbx

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README | LICENSE

README.md (3808B)

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