improved readme and code documentation

Author: basvanbeek

README.md

@@ -1,2 +1,100 @@
 # ocsql
-OpenCensus SQL database driver wrapper
+OpenCensus SQL database driver wrapper.
+
+Add an ocsql wrapper to your existing database code to instrument the
+interactions with the database.
+
+## initialize
+
+To use ocsql with your application, register an ocsql wrapper of a database
+driver as shown below.
+
+Example:
+```go
+import (
+    "github.com/basvanbeek/ocsql"
+    _ "github.com/mattn/go-sqlite3"
+)
+
+var (
+    driverName string
+    err        error
+    db         *sql.DB
+)
+
+// Register our ocsql wrapper for the provided SQLite3 driver.
+driverName, err = ocsql.Register("sqlite3", ocsql.WithOptions(ocsql.TraceAll))
+if err != nil {
+    log.Fatalf("unable to register our ocsql driver: %v\n", err)
+}
+
+// Connect to a SQLite3 database using the ocsql driver wrapper.
+db, err = sql.Open(driverName, "resource.db")
+```
+
+If not wanting to use the named driver magic used by ocsql.Register, an
+alternative way to bootstrap the ocsql wrapper exists.
+
+Example:
+```go
+import (
+    "github.com/basvanbeek/ocsql"
+    sqlite3 "github.com/mattn/go-sqlite3"
+)
+
+var (
+    driver driver.Driver
+    err    error
+    db     *sql.DB
+)
+
+// Explicitly wrap the SQLite3 driver with ocsql
+driver = ocsql.Wrap(&sqlite3.SQLiteDriver{})
+
+// Register our ocsql wrapper as a database driver
+sql.Register("ocsql-sqlite3", driver)
+
+// Connect to a SQLite3 database using the ocsql driver wrapper
+db, err = sql.Open("ocsql-sqlite3", "resource.db")
+```
+
+## context
+
+To really take advantage of ocsql, all database calls should be made using the
+*Context methods. Failing to do so will result in many orphaned ocsql traces
+if the `AllowRoot` TraceOption is set to true. By default AllowRoot is disabled
+and will result in ocsql not tracing the database calls if context or parent
+spans are missing.
+
+| Old            | New                   |
+|----------------|-----------------------|
+| *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   |
+
+Example:
+```go
+
+func (s *svc) GetDevice(ctx context.Context, id int) (*Device, error) {
+    // assume we have instrumented our service transports and ctx holds a span.
+    var device Device
+    if err := s.db.QueryRowContext(
+        ctx, "SELECT * FROM device WHERE id = ?", id,
+    ).Scan(&device); err != nil {
+        return nil, err
+    }
+    return device
+}
+```

driver.go

@@ -22,6 +22,8 @@ var (
 // Register initializes and registers our ocsql wrapped database driver
 // identified by its driverName and using provided TraceOptions. On success it
 // returns the generated driverName to use when calling sql.Open.
+// It is possible to register multiple wrappers for the same database driver if
+// needing different TraceOptions for different connections.
 func Register(driverName string, options ...TraceOption) (string, error) {
 	// retrieve the driver implementation we need to wrap with instrumentation
 	db, err := sql.Open(driverName, "")
@@ -38,7 +40,7 @@ func Register(driverName string, options ...TraceOption) (string, error) {
 
 	// Since we might want to register multiple ocsql drivers to have different
 	// TraceOptions, but potentially the same underlying database driver, we
-	// cycle through available driver names.
+	// cycle through to find available driver names.
 	driverName = driverName + "-ocsql-"
 	for i := int64(0); i < 100; i++ {
 		var (

options.go

@@ -1,19 +1,53 @@
 package ocsql
 
-// TraceOption allows for functional options.
+// TraceOption allows for managing ocsql configuration using functional options.
 type TraceOption func(o *TraceOptions)
 
 // TraceOptions holds configuration of our ocsql 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.
 type TraceOptions struct {
-	AllowRoot    bool
-	Transaction  bool
-	Ping         bool
-	RowsNext     bool
-	RowsClose    bool
+	// AllowRoot, if set to true, will allow ocsql to create root spans in
+	// absence of exisiting spans or even context.
+	// Default is to not trace ocsql calls if no existing parent span is found
+	// in context or when using methods not taking context.
+	AllowRoot bool
+
+	// Transaction, if set to true, will create spans for the duration of db
+	// transactions. All spans created by the transaction's scoped queries will
+	// become children of the transaction span.
+	Transaction bool
+
+	// Ping, if set to true, will enable the creation of spans on Ping requests.
+	Ping bool
+
+	// RowsNext, if set to true, will enable the creation of spans on RowsNext
+	// calls. This can result in many spans.
+	RowsNext bool
+
+	// RowsClose, if set to true, will enable the creation of spans on RowsClose
+	// calls.
+	RowsClose bool
+
+	// RowsAffected, if set to true, will enable the creation of spans on
+	// RowsAffected calls.
 	RowsAffected bool
+
+	// LastInsertID, if set to true, will enable the creation of spans on
+	// LastInsertId calls.
 	LastInsertID bool
-	Query        bool
-	QueryParams  bool
+
+	// Query, 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
+
+	// QueryParams, if set to true, will enable recording of parameters used
+	// with parametrized queries. Only allow this if it is safe to have
+	// parameters recorded with respect to security.
+	// This setting is a noop if the Query option is set to false.
+	QueryParams bool
 }
 
 // TraceAll has all tracing options enabled.
@@ -37,65 +71,77 @@ func WithOptions(options TraceOptions) TraceOption {
 	}
 }
 
-// WithAllowRoot when set to true will allow ocsql to create root spans. If
-// no context is provided to (the majority) of database/sql commands this will
-// result in many single span traces.
+// WithAllowRoot if set to true, will allow ocsql to create root spans in
+// absence of exisiting spans or even context.
+// Default is to not trace ocsql calls if no existing parent span is found
+// in context or when using methods not taking context.
 func WithAllowRoot(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.AllowRoot = b
 	}
 }
 
-// WithTransaction enables / disables creation of transaction spans.
+// WithTransaction if set to true, will create spans for the duration of db
+// transactions. All spans created by the transaction's scoped queries will
+// become children of the transaction span.
 func WithTransaction(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.Transaction = b
 	}
 }
 
-// WithPing enables / disables tracing of database Ping calls.
+// WithPing if set to true, will enable the creation of spans on Ping requests.
 func WithPing(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.Ping = b
 	}
 }
 
-// WithRowsNext enables / disables tracing of database Rows.Next calls.
+// WithRowsNext if set to true, will enable the creation of spans on RowsNext
+// calls. This can result in many spans.
 func WithRowsNext(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.RowsNext = b
 	}
 }
 
-// WithRowsClose enables / disables tracing of database Rows.Close calls.
+// WithRowsClose if set to true, will enable the creation of spans on RowsClose
+// calls.
 func WithRowsClose(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.RowsClose = b
 	}
 }
 
-// WithRowsAffected enables / disables tracing of database Result.RowsAffected calls.
+// WithRowsAffected if set to true, will enable the creation of spans on
+// RowsAffected calls.
 func WithRowsAffected(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.RowsAffected = b
 	}
 }
 
-// WithLastInsertID enables / disables tracing of database Result.LastInsertId calls.
+// WithLastInsertID if set to true, will enable the creation of spans on
+// LastInsertId calls.
 func WithLastInsertID(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.LastInsertID = b
 	}
 }
 
-// WithQuery enables / disables annotating of database sql queries.
+// WithQuery 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 {
 	return func(o *TraceOptions) {
 		o.Query = b
 	}
 }
 
-// WithQueryParams enables / disables tracing of database query parameters.
+// WithQueryParams if set to true, will enable recording of parameters used
+// with parametrized queries. Only allow this if it is safe to have
+// parameters recorded with respect to security.
+// This setting is a noop if the Query option is set to false.
 func WithQueryParams(b bool) TraceOption {
 	return func(o *TraceOptions) {
 		o.QueryParams = b