chore: renamed trace options to be more intuitive.

README.md

@@ -1,27 +1,79 @@
 # Zipkin instrumentation SQL
 
-A sql wrapper including Zipkin instrumentation
+[![Build Status](https://travis-ci.com/jcchavezs/zipkin-instrumentation-sql.svg?branch=master)](https://travis-ci.com/jcchavezs/zipkin-instrumentation-sql)
+[![Go Report Card](https://goreportcard.com/badge/github.com/jcchavezs/zipkin-instrumentation-sql)](https://goreportcard.com/report/github.com/jcchavezs/zipkin-instrumentation-sql)
+[![GoDoc](https://godoc.org/github.com/jcchavezs/zipkin-instrumentation-sql?status.svg)](https://godoc.org/github.com/jcchavezs/zipkin-instrumentation-sql)
+[![Sourcegraph](https://sourcegraph.com/github.com/jcchavezs/zipkin-instrumentation-sql/-/badge.svg)](https://sourcegraph.com/github.com/jcchavezs/zipkin-instrumentation-sql?badge)
+
+A SQL wrapper including Zipkin instrumentation
 
 ## Usage
 
 ```go
 import (
  _ "github.com/go-sql-driver/mysql"
  zipkinsql "github.com/jcchavezs/zipkin-instrumentation-sql"
+ zipkin "github.com/openzipkin/zipkin-go"
 )
 
 var (
  driverName string
  err error
  db *sql.DB
+ tracer *zipkin.Tracer
 )
 
 // Register our zipkinsql wrapper for the provided MySQL driver.
-driverName, err = zipkinsql.Register("mysql", zipkinsql.WithAllTraceOptions())
+driverName, err = zipkinsql.Register("mysql", tracer, zipkinsql.WithAllTraceOptions())
 if err != nil {
  log.Fatalf("unable to register zipkin driver: %v\n", err)
 }
 
-// Connect to a MySQL database using the ocsql driver wrapper.
+// Connect to a MySQL database using the zipkinsql driver wrapper.
 db, err = sql.Open(driverName, "myDSN")
-```
+```
+
+You can also wrap your own driver with zipkin instrumentation as follows:
+
+```go
+
+import (
+ mysql "github.com/go-sql-driver/mysql"
+ "github.com/opencensus-integrations/zipkinsql"
+)
+
+var (
+ driver driver.Driver
+ err error
+ db *sql.DB
+ tracer *zipkin.Tracer
+)
+
+// Explicitly wrap the MySQL driver with zipkinsql
+driver = zipkinsql.Wrap(&mysql.MySQLDriver{}, tracer)
+
+// Register our zipkinsql wrapper as a database driver
+sql.Register("zipkinsql-mysql", driver)
+
+// Connect to a MySQL database using the zipkinsql driver wrapper
+db, err = sql.Open("zipkinsql-mysql", "myDSN")
+```
+
+## Usage of *Context methods
+
+Instrumentation is possible if the context is being passed downstream in methods.
+This is not only for instrumentation purposes but also a [good practice](https://medium.com/@cep21/how-to-correctly-use-context-context-in-go-1-7-8f2c0fafdf39) in go programming. `database/sql` package exposes already a set of methods that receive the context as first paramenter:
+
+- `*DB.Begin` -> `*DB.BeginTx`
+- `*DB.Exec` -> `*DB.ExecContext`
+- `*DB.Ping` -> `*DB.PingContext`
+- `*DB.Prepare` -> `*DB.PrepareContext`
+- `*DB.Query` -> `*DB.QueryContext`
+- `*DB.QueryRow` -> `*DB.QueryRowContext`
+- `*Stmt.Exec` -> `*Stmt.ExecContext`
+- `*Stmt.Query` -> `*Stmt.QueryContext`
+- `*Stmt.QueryRow` -> `*Stmt.QueryRowContext`
+- `*Tx.Exec` -> `*Tx.ExecContext`
+- `*Tx.Prepare` -> `*Tx.PrepareContext`
+- `*Tx.Query` -> `*Tx.QueryContext`
+- `*Tx.QueryRow` -> `*Tx.QueryRowContext`

driver.go

@@ -175,7 +175,7 @@ func (c zConn) ExecContext(ctx context.Context, query string, args []driver.Name
  span, _ := c.tracer.StartSpanFromContext(ctx, "sql/exec")
  defer span.Finish()
 
- if c.options.Query {
+ if c.options.TagQuery {
  span.Tag("sql.query", query)
  }
 
@@ -209,7 +209,7 @@ func (c zConn) QueryContext(ctx context.Context, query string, args []driver.Nam
  span, _ := c.tracer.StartSpanFromContext(ctx, "sql/exec")
  defer span.Finish()
 
- if c.options.Query {
+ if c.options.TagQuery {
  span.Tag("sql.query", query)
  }
 
@@ -293,7 +293,7 @@ type zResult struct {
 }
 
 func (r zResult) LastInsertId() (int64, error) {
- if !r.options.LastInsertID {
+ if !r.options.LastInsertIDSpan {
  return r.driver.LastInsertId()
  }
 
@@ -310,7 +310,7 @@ func (r zResult) LastInsertId() (int64, error) {
 
 func (r zResult) RowsAffected() (cnt int64, err error) {
  zipkin.SpanFromContext(r.ctx)
- if r.options.RowsAffected && zipkin.SpanFromContext(r.ctx) != nil {
+ if r.options.RowsAffectedSpan && zipkin.SpanFromContext(r.ctx) != nil {
  span, _ := r.tracer.StartSpanFromContext(r.ctx, "sql/rows_affected")
  setSpanDefaultTags(span, r.options.DefaultTags)
  defer func() {
@@ -359,7 +359,7 @@ func (s zStmt) ExecContext(ctx context.Context, args []driver.NamedValue) (res d
  span.Finish()
  }()
 
- if s.options.Query {
+ if s.options.TagQuery {
  span.Tag("sql.query", s.query)
  }
 
@@ -370,6 +370,13 @@ func (s zStmt) ExecContext(ctx context.Context, args []driver.NamedValue) (res d
  if err != nil {
  return nil, err
  }
+
+ if s.options.TagAffectedRows {
+ if affectedRows, err := res.RowsAffected(); err != nil {
+ span.Tag("sql.affected_rows", fmt.Sprintf("%d", affectedRows))
+ }
+ }
+
  res, err = zResult{driver: res, ctx: ctx, options: s.options}, nil
  return
 }
@@ -385,7 +392,7 @@ func (s zStmt) QueryContext(ctx context.Context, args []driver.NamedValue) (rows
  span.Finish()
  }()
 
- if s.options.Query {
+ if s.options.TagQuery {
  span.Tag("sql.query", s.query)
  }
 
@@ -402,6 +409,7 @@ func (s zStmt) QueryContext(ctx context.Context, args []driver.NamedValue) (rows
  if err != nil {
  return nil, err
  }
+
  rows, err = zRows{driver: rows, ctx: ctx, options: s.options}, nil
  return
 }

options.go

@@ -4,22 +4,24 @@ package zipkinsql
 type TraceOption func(o *TraceOptions)
 
 // TraceOptions holds configuration of our zipkinsql tracing middleware.
-// By default all options are set to false intentionally when creating a wrapped
-// driver and provide the most sensible default with both performance and
-// security in mind.
+// By default all boolean options are set to false intentionally when creating
+// a wrapped driver and provide the most sensible default with both performance
+// and security in mind.
 type TraceOptions struct {
- // RowsAffected, if set to true, will enable the creation of spans on
- // RowsAffected calls.
- RowsAffected bool
+ // LastInsertIDSpan, if set to true, will enable the creation of spans on
+ // LastInsertId calls.
+ LastInsertIDSpan bool
+
+ // RowsAffectedSpan, if set to true, will enable the creation of spans on
+ // RowsAffectedSpan calls.
+ RowsAffectedSpan bool
 
- // Query, if set to true, will enable recording of sql queries in spans.
+ // TagQuery, if set to true, will enable recording of sql queries in spans.
  // Only allow this if it is safe to have queries recorded with respect to
  // security.
- Query bool
+ TagQuery bool
 
- // LastInsertID, if set to true, will enable the creation of spans on
- // LastInsertId calls.
- LastInsertID bool
+ TagAffectedRows bool
 
  // DefaultTags will be set to each span as default.
  DefaultTags map[string]string
@@ -34,41 +36,50 @@ func WithAllTraceOptions() TraceOption {
 
 // AllTraceOptions has all tracing options enabled.
 var AllTraceOptions = TraceOptions{
- RowsAffected: true,
- Query: true,
- LastInsertID: true,
+ RowsAffectedSpan: true,
+ LastInsertIDSpan: true,
+ TagQuery: true,
+ TagAffectedRows: true,
 }
 
-// WithOptions sets our ocsql tracing middleware options through a single
+// WithOptions sets the zipkinsql tracing middleware options through a single
 // TraceOptions object.
 func WithOptions(options TraceOptions) TraceOption {
  return func(o *TraceOptions) {
  *o = options
  }
 }
 
-// WithRowsAffected if set to true, will enable the creation of spans on
+// WithRowsAffectedSpan if set to true, will enable the creation of spans on
 // RowsAffected calls.
-func WithRowsAffected(b bool) TraceOption {
+func WithRowsAffectedSpan(b bool) TraceOption {
  return func(o *TraceOptions) {
- o.RowsAffected = b
+ o.RowsAffectedSpan = b
  }
 }
 
-// WithLastInsertID if set to true, will enable the creation of spans on
+// WithLastInsertIDSpan if set to true, will enable the creation of spans on
 // LastInsertId calls.
-func WithLastInsertID(b bool) TraceOption {
+func WithLastInsertIDSpan(b bool) TraceOption {
  return func(o *TraceOptions) {
- o.LastInsertID = b
+ o.LastInsertIDSpan = b
  }
 }
 
-// WithQuery if set to true, will enable recording of sql queries in spans.
+// WithTagQuery if set to true, will enable recording of SQL queries in spans.
 // Only allow this if it is safe to have queries recorded with respect to
 // security.
-func WithQuery(b bool) TraceOption {
+func WithTagQuery(b bool) TraceOption {
+ return func(o *TraceOptions) {
+ o.TagQuery = b
+ }
+}
+
+// WithTagAffectedRows if set to true, will enable recording of the affected rows
+// number in spans.
+func WithTagAffectedRows(b bool) TraceOption {
  return func(o *TraceOptions) {
- o.Query = b
+ o.TagAffectedRows = b
  }
 }