[doc] add instrumentations and minor improvement (#52)

* document instrumentation and some adjustment to instrumentation ops naming

* rename doc tabs. main.go and main_test.go now Example and Mock respectively

* fix import order

* added missing test

* update badges

Author: Fs02

README.md

@@ -1,5 +1,10 @@
 # REL
-[![GoDoc](https://godoc.org/github.com/Fs02/rel?status.svg)](https://godoc.org/github.com/Fs02/rel) [![Build Status](https://travis-ci.com/Fs02/rel.svg?branch=master)](https://travis-ci.com/Fs02/rel) [![Go Report Card](https://goreportcard.com/badge/github.com/Fs02/rel)](https://goreportcard.com/report/github.com/Fs02/rel) [![Maintainability](https://api.codeclimate.com/v1/badges/d487e2be0ed7b0b1fed1/maintainability)](https://codeclimate.com/github/Fs02/rel/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/d487e2be0ed7b0b1fed1/test_coverage)](https://codeclimate.com/github/Fs02/rel/test_coverage)
+
+[![GoDoc](https://godoc.org/github.com/Fs02/rel?status.svg)](https://godoc.org/github.com/Fs02/rel)
+[![Build Status](https://travis-ci.com/Fs02/rel.svg?branch=master)](https://travis-ci.com/Fs02/rel)
+[![Go Report Card](https://goreportcard.com/badge/github.com/Fs02/rel)](https://goreportcard.com/report/github.com/Fs02/rel)
+[![Maintainability](https://api.codeclimate.com/v1/badges/194611cc82f02edcda6e/maintainability)](https://codeclimate.com/github/Fs02/rel/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/194611cc82f02edcda6e/test_coverage)](https://codeclimate.com/github/Fs02/rel/test_coverage)
 
 > Golang SQL Database Layer for Layered Architecture.
 

adapter/postgres/postgres.go

@@ -89,7 +89,7 @@ func (adapter *Adapter) query(ctx context.Context, statement string, args []inte
 		rows *db.Rows
 	)
 
-	finish := adapter.Instrument(ctx, "query", statement)
+	finish := adapter.Instrument(ctx, "adapter-query", statement)
 	if adapter.Tx != nil {
 		rows, err = adapter.Tx.QueryContext(ctx, statement, args...)
 	} else {

adapter/sql/adapter.go

@@ -63,7 +63,7 @@ func (adapter *Adapter) Aggregate(ctx context.Context, query rel.Query, mode str
 		statement, args = NewBuilder(adapter.Config).Aggregate(query, mode, field)
 	)
 
-	finish := adapter.Instrument(ctx, "aggregate", statement)
+	finish := adapter.Instrument(ctx, "adapter-aggregate", statement)
 	if adapter.Tx != nil {
 		err = adapter.Tx.QueryRowContext(ctx, statement, args...).Scan(&out)
 	} else {
@@ -80,7 +80,7 @@ func (adapter *Adapter) Query(ctx context.Context, query rel.Query) (rel.Cursor,
 		statement, args = NewBuilder(adapter.Config).Find(query)
 	)
 
-	finish := adapter.Instrument(ctx, "query", statement)
+	finish := adapter.Instrument(ctx, "adapter-query", statement)
 	rows, err := adapter.query(ctx, statement, args)
 	finish(err)
 
@@ -97,7 +97,7 @@ func (adapter *Adapter) query(ctx context.Context, statement string, args []inte
 
 // Exec performs exec operation.
 func (adapter *Adapter) Exec(ctx context.Context, statement string, args []interface{}) (int64, int64, error) {
-	finish := adapter.Instrument(ctx, "exec", statement)
+	finish := adapter.Instrument(ctx, "adapter-exec", statement)
 	res, err := adapter.exec(ctx, statement, args)
 	finish(err)
 
@@ -186,7 +186,7 @@ func (adapter *Adapter) Begin(ctx context.Context) (rel.Adapter, error) {
 		err       error
 	)
 
-	finish := adapter.Instrument(ctx, "transaction", "begin transaction")
+	finish := adapter.Instrument(ctx, "adapter-begin", "begin transaction")
 
 	if adapter.Tx != nil {
 		tx = adapter.Tx
@@ -209,7 +209,7 @@ func (adapter *Adapter) Begin(ctx context.Context) (rel.Adapter, error) {
 func (adapter *Adapter) Commit(ctx context.Context) error {
 	var err error
 
-	finish := adapter.Instrument(ctx, "transaction", "commit transaction")
+	finish := adapter.Instrument(ctx, "adapter-commit", "commit transaction")
 
 	if adapter.Tx == nil {
 		err = errors.New("unable to commit outside transaction")
@@ -228,7 +228,7 @@ func (adapter *Adapter) Commit(ctx context.Context) error {
 func (adapter *Adapter) Rollback(ctx context.Context) error {
 	var err error
 
-	finish := adapter.Instrument(ctx, "transaction", "rollback transaction")
+	finish := adapter.Instrument(ctx, "adapter-rollback", "rollback transaction")
 
 	if adapter.Tx == nil {
 		err = errors.New("unable to rollback outside transaction")

docs/_sidebar.md

@@ -32,5 +32,6 @@
     * [Modifying Association](association.md#modifying-association)
 
 * [Transactions](transactions.md)
+* [Instrumentation](instrumentation.md)
 * [Adapters](adapters.md)
 * [Github](https://github.com/Fs02/rel)

docs/association.md

@@ -53,7 +53,7 @@ Preload will load association to structs. To preload association, use `Preload`.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 // preload transaction `belongs to` buyer association.
@@ -73,7 +73,7 @@ repo.Preload(ctx, &user, "transactions", where.Eq("paid", true))
 repo.Preload(ctx, &transactions, "buyer.address")
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // preload transaction `belongs to` buyer association.
@@ -103,7 +103,7 @@ REL will try to create a new record for association if `ID` is a zero value.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 user := User{
@@ -118,7 +118,7 @@ user := User{
 repo.Insert(ctx, &user)
 ```
 
-### **main_tesst.go**
+### **Mock**
 
 ```go
 repo.ExpectInsert().For(&user)
@@ -130,7 +130,7 @@ REL will try to update a new record for association if `ID` is a zero value. To
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 userId := 1
@@ -150,7 +150,7 @@ user := User{
 repo.Update(ctx, &user)
 ```
 
-### **main_tesst.go**
+### **Mock**
 
 ```go
 repo.ExpectUpdate().For(&user)
@@ -162,7 +162,7 @@ To selectively update only specific fields or association, `use rel.Map`.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 modification := rel.Map{
@@ -175,7 +175,7 @@ modification := rel.Map{
 repo.Update(ctx, &user, modification)
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 modification := rel.Map{

docs/crud.md

@@ -6,7 +6,7 @@ A new record can be inserted to database using a struct, map or set function. To
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 book := Book{
@@ -20,7 +20,7 @@ if err := repo.Insert(ctx, &book); err != nil {
 }
 ```
 
-### **main_test.go**
+### **Mock**
 
 > reltest.Repository will automatically sets any primary key value to be 1.
 
@@ -50,7 +50,7 @@ To insert a new record using a map, simply pass a `rel.Map` as the second argume
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 var book Book
@@ -63,7 +63,7 @@ data := rel.Map{
 repo.Insert(ctx, &book, data)
 ```
 
-### **main_test.go**
+### **Mock**
 
 > reltest.Repository will automatically populate record using value provided by map.
 
@@ -81,14 +81,14 @@ It's also possible to insert a new record manually using `rel.Set`, which is a v
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 // Insert using set.
 repo.Insert(ctx, &book, rel.Set("title", "Rel for dummies"), rel.Set("category", "education"))
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect insertion with given modifier.
@@ -105,14 +105,14 @@ To inserts multiple records at once, use `InsertAll`.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 // InsertAll books.
 repo.InsertAll(ctx, &books)
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect any insert all.
@@ -129,16 +129,17 @@ REL provides a powerful API for querying record from database. To query a single
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
+// Retrieve a book with id 1
 repo.Find(ctx, &book, rel.Eq("id", 1))
 
 // OR: with sugar alias
 repo.Find(ctx, &book, where.Eq("id", 1))
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect a find query and mock the result.
@@ -155,13 +156,13 @@ To query multiple records, use `FindAll` method.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 repo.FindAll(ctx, &books, where.Like("title", "%dummies%").AndEq("category", "education"), rel.Limit(10))
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect a find all query and mock the result.
@@ -175,14 +176,14 @@ REL also support chainable query api for a more complex query use case.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 query := rel.Select("title", "category").Where(where.Eq("category", "education")).SortAsc("title")
 repo.FindAll(ctx, &books, query)
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect a find all query and mock the result.
@@ -200,14 +201,14 @@ Similar to create, updating a record in REL can also be done using struct, map o
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 // Update directly using struct.
 repo.Update(ctx, &book)
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect any update is called.
@@ -220,14 +221,14 @@ Besides struct, map and set function. There's also increment and decrement modif
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 // Update directly using struct.
 repo.Update(ctx, &book, rel.Inc("views"))
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect any update is called.
@@ -244,14 +245,14 @@ To delete a record in rel, simply pass the record to be deleted.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 // Delete a record.
 repo.Delete(ctx, &book)
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect book to be deleted.
@@ -265,14 +266,14 @@ Deleting multiple records is possible using `DeleteAll`.
 
 <!-- tabs:start -->
 
-### **main.go**
+### **Example**
 
 ```go
 // We have manually define the table here.
 repo.DeleteAll(ctx, rel.From("books").Where(where.Eq("id", 1)))
 ```
 
-### **main_test.go**
+### **Mock**
 
 ```go
 // Expect books to be deleted.

docs/instrumentation.go

@@ -0,0 +1,23 @@
+package main
+
+import (
+	"context"
+	"log"
+	"time"
+
+	"github.com/Fs02/rel"
+)
+
+// Instrumentation docs example.
+func Instrumentation(ctx context.Context, repo rel.Repository) {
+	/// [instrumentation]
+	repo.Instrumentation(func(ctx context.Context, op string, message string) func(err error) {
+		t := time.Now()
+
+		return func(err error) {
+			duration := time.Since(t)
+			log.Print("[duration: ", duration, " op: ", op, "] ", message, " - ", err)
+		}
+	})
+	/// [instrumentation]
+}