Add sub-package extra.

Squashed commit of the following:

commit 059a3fc4513050043e53dffcd7316c8938a2cd06
Author: cfchou <cfchou@gmail.com>
Date:   Sun Aug 27 18:02:22 2017 +0800

    go fmt

commit d3949ba
Author: cfchou <cfchou@gmail.com>
Date:   Sun Aug 27 16:54:32 2017 +0800

    add doc. add tracing example.

commit 7e27427
Author: cfchou <cfchou@gmail.com>
Date:   Sun Aug 27 10:58:39 2017 +0800

    shorten ExponentialBackOff, ConstantBackOff to ExpBackOff ConstBackOff respectively

commit aac3055
Author: cfchou <cfchou@gmail.com>
Date:   Sun Aug 27 10:46:00 2017 +0800

    doc update

commit 5377a01
Author: cfchou <cfchou@gmail.com>
Date:   Sat Aug 26 16:48:49 2017 +0800

    drop go1.9 for now, travis-ci hasn't supported

commit 1a5e48f
Author: cfchou <cfchou@gmail.com>
Date:   Sat Aug 26 16:44:54 2017 +0800

    drop go1.7, add go1.9

commit e0d1dec
Author: cfchou <cfchou@gmail.com>
Date:   Sat Aug 26 15:47:45 2017 +0800

    prometheus tests

commit 7617646
Author: cfchou <cfchou@gmail.com>
Date:   Fri Aug 25 23:48:14 2017 +0800

    extra/metric/prometheus

commit 8a65337
Author: cfchou <cfchou@gmail.com>
Date:   Thu Aug 24 23:31:03 2017 +0800

    extra/metric/statsd examples

commit af0ecf0
Author: cfchou <cfchou@gmail.com>
Date:   Thu Aug 24 13:57:12 2017 +0800

    add extra/metric

commit 25d3274
Author: cfchou <cfchou@gmail.com>
Date:   Thu Aug 24 11:34:31 2017 +0800

    update Makefile

commit eeb7c87
Author: cfchou <cfchou@gmail.com>
Date:   Thu Aug 24 00:47:06 2017 +0800

    extra/log

commit f7a33a1
Author: cfchou <cfchou@gmail.com>
Date:   Wed Aug 23 21:01:31 2017 +0800

    re-arch package

commit f7bb02f
Merge: 07cdc65 3ced204
Author: cfchou <cfchou@gmail.com>
Date:   Wed Aug 23 01:03:49 2017 +0800

    improve doc

commit 07cdc65
Author: cfchou <cfchou@gmail.com>
Date:   Tue Aug 22 16:55:26 2017 +0800

    example of logger

commit 096b017
Author: cfchou <cfchou@gmail.com>
Date:   Tue Aug 22 00:32:14 2017 +0800

    replaceable Logger

commit f8b7adc
Author: cfchou <cfchou@gmail.com>
Date:   Mon Aug 21 17:56:55 2017 +0800

    tmp

commit d25e4c5
Author: cfchou <cfchou@gmail.com>
Date:   Mon Aug 21 15:00:06 2017 +0800

    improve doc

commit 52c10ea
Author: cfchou <cfchou@gmail.com>
Date:   Mon Aug 21 12:32:46 2017 +0800

    tmp

.travis.yml

@@ -1,8 +1,8 @@
 language: go
 
 go:
-  - 1.7.x
   - 1.8.x
+  - tip
 install:
   - go get -v github.com/mattn/goveralls
   - go get -v github.com/Masterminds/glide

Makefile

@@ -5,33 +5,38 @@ PACKAGE := $(shell glide nv)
 .PHONY: format-and-test
 format-and-test: format test
 
+.PHONY: clean
+clean:
+	@rm -rf cover_*.out
+
 .PHONY: test
-test:
-	go test -v -race -cover $(PACKAGE) -quickchecks 50 -level crit
+test: clean
+	#go test -v -race -cover ./extra/...
+	#go test -v -race -cover ./gentle/... -quickchecks 50 -level crit
+	@rm -rf cover_*.out
+	go test -v -race -covermode=atomic -coverprofile=cover_all.out ./extra/log
+	go test -v -race -covermode=atomic -coverprofile=cover_extra_metric.out ./extra/metric
+	@env grep -v mode cover_extra_metric.out >>cover_all.out
+	go test -v -race -covermode=atomic -coverprofile=cover_gentle.out ./gentle -quickchecks 50 -level crit
+	@env grep -v mode cover_gentle.out >>cover_all.out
 
 .PHONY: format
 format:
 	go fmt $(PACKAGE)
 	go vet $(PACKAGE)
 
-.PHONY: cover
-cover:
-	@rm -rf cover.out
-	go test -v -coverprofile=cover.out $(PACKAGE) -quickchecks 10 -level crit
-	go tool cover -html=cover.out -o cover.html
-
 .PHONY: lint
-lint:
-	go fmt $(PACKAGE)
-	go vet $(PACKAGE)
+lint: format
 	golint $(PACKAGE)
-	@# Run again with magic to exit non-zero if golint outputs anything.
-	@! (golint ./gentle/... | read dummy)
-	go vet $(PACKAGE)
+
+.PHONY: cover
+cover: test
+	go tool cover -html=cover_all.out -o cover.html
+	make clean
 
 .PHONY: coveralls
-coveralls:
-	@rm -rf cover.out
-	go test -v -covermode=count -coverprofile=cover.out $(PACKAGE) -quickchecks 50 -level crit
-	goveralls -coverprofile=cover.out -service=travis-ci
+coveralls: test
+	goveralls -coverprofile=cover_all.out -service=travis-ci
+	make clean
+
 

extra/doc.go

@@ -0,0 +1,17 @@
+/*
+Package extra provides supplement components for the sibling package
+gentle(https://godoc.org/github.com/cfchou/go-gentle/gentle).
+
+
+Logging
+
+Sub package log(https://godoc.org/github.com/cfchou/go-gentle/extra/log)
+contains adaptors of gentle.Logger for different logging libraries.
+
+Metrics
+
+Sub package metric(https://godoc.org/github.com/cfchou/go-gentle/extra/metric)
+contains adaptors of metrics collectors used for gentle-ments in gentle.
+
+*/
+package extra

extra/log/doc.go

@@ -0,0 +1,6 @@
+/*
+Package log contains adaptors of gentle.Logger for different logging libraries.
+Currently log15 and logrus are supported.
+
+*/
+package log

extra/log/example_log15_test.go

@@ -0,0 +1,57 @@
+package log
+
+import (
+	"context"
+	"gopkg.in/cfchou/go-gentle.v3/gentle"
+	"gopkg.in/inconshreveable/log15.v2"
+	"strconv"
+	"time"
+)
+
+func ExampleNewLog15Adapter_package() {
+	// set up log level for package-global logger
+	logger := log15.New()
+	h := log15.LvlFilterHandler(log15.LvlDebug, log15.StdoutHandler)
+	logger.SetHandler(h)
+	gentle.Log = NewLog15Adapter(logger)
+
+	msgID := 0
+	var fakeStream gentle.SimpleStream = func(_ context.Context) (gentle.Message, error) {
+		defer func() { msgID++ }()
+		return gentle.SimpleMessage(strconv.Itoa(msgID)), nil
+	}
+
+	limiter := gentle.NewTokenBucketRateLimit(10*time.Millisecond, 1)
+	stream := gentle.NewRateLimitedStream(
+		gentle.NewRateLimitedStreamOpts("", "test", limiter),
+		fakeStream)
+
+	// log:
+	// t=2017-08-23T23:50:50+0800 lvl=info msg="[Stream] Get(), no span" namespace= gentle=sRate name=test err="No parent span"
+	// t=2017-08-23T23:50:50+0800 lvl=dbug msg="[Stream] Get() ok" namespace= gentle=sRate name=test msgOut=0 timespan=0.000
+	stream.Get(context.Background())
+	// Output:
+}
+
+func ExampleNewLog15Adapter_stream() {
+	// set up log level for stream logger
+	msgID := 0
+	var fakeStream gentle.SimpleStream = func(_ context.Context) (gentle.Message, error) {
+		defer func() { msgID++ }()
+		return gentle.SimpleMessage(strconv.Itoa(msgID)), nil
+	}
+
+	limiter := gentle.NewTokenBucketRateLimit(10*time.Millisecond, 1)
+
+	opts := gentle.NewRateLimitedStreamOpts("", "test2", limiter)
+	ll := log15.New()
+	ll.SetHandler(log15.LvlFilterHandler(log15.LvlDebug, log15.StdoutHandler))
+	opts.Log = NewLog15Adapter(ll)
+	stream := gentle.NewRateLimitedStream(opts, fakeStream)
+
+	// log:
+	// t=2017-08-23T23:54:46+0800 lvl=info msg="[Stream] Get(), no span" err="No parent span"
+	// t=2017-08-23T23:54:46+0800 lvl=dbug msg="[Stream] Get() ok" msgOut=0 timespan=0.000
+	stream.Get(context.Background())
+	// Output:
+}

extra/log/example_logrus_test.go

@@ -0,0 +1,54 @@
+package log
+
+import (
+	"context"
+	"gopkg.in/cfchou/go-gentle.v3/gentle"
+	"gopkg.in/sirupsen/logrus.v1"
+	"strconv"
+	"time"
+)
+
+func ExampleNewLogusLogger_package() {
+	// Demo how to replace package-global logger with logrus logger
+	ll := logrus.New()
+	ll.SetLevel(logrus.InfoLevel)
+	// replace package-global logger
+	gentle.Log = NewLogusLogger(ll)
+
+	msgID := 0
+	var fakeStream gentle.SimpleStream = func(_ context.Context) (gentle.Message, error) {
+		defer func() { msgID++ }()
+		return gentle.SimpleMessage(strconv.Itoa(msgID)), nil
+	}
+
+	limiter := gentle.NewTokenBucketRateLimit(10*time.Millisecond, 1)
+	stream := gentle.NewRateLimitedStream(
+		gentle.NewRateLimitedStreamOpts("", "test", limiter),
+		fakeStream)
+	// log:
+	// time="2017-08-23T23:56:14+08:00" level=info msg="[Stream] Get(), no span" err="No parent span" gentle=sRate name=test namespace=
+	stream.Get(context.Background())
+	// Output:
+}
+
+func ExampleNewLogusLogger_stream() {
+	msgID := 0
+	var fakeStream gentle.SimpleStream = func(_ context.Context) (gentle.Message, error) {
+		defer func() { msgID++ }()
+		return gentle.SimpleMessage(strconv.Itoa(msgID)), nil
+	}
+
+	limiter := gentle.NewTokenBucketRateLimit(10*time.Millisecond, 1)
+	opts := gentle.NewRateLimitedStreamOpts("", "test2", limiter)
+	// replace stream2's logger with logrus one and set its level to debug
+	ll := logrus.New()
+	ll.SetLevel(logrus.DebugLevel)
+	opts.Log = NewLogusLogger(ll)
+	stream := gentle.NewRateLimitedStream(opts, fakeStream)
+
+	// log:
+	// time="2017-08-23T23:57:11+08:00" level=info msg="[Stream] Get(), no span" err="No parent span"
+	// time="2017-08-23T23:57:11+08:00" level=debug msg="[Stream] Get() ok" msgOut=0 timespan=2.6865e-05
+	stream.Get(context.Background())
+	// Output:
+}

extra/log/log15.go

@@ -0,0 +1,22 @@
+package log
+
+import (
+	"gopkg.in/cfchou/go-gentle.v3/gentle"
+	"gopkg.in/inconshreveable/log15.v2"
+)
+
+type Log15Adapter struct {
+	log15.Logger
+}
+
+func NewLog15Adapter(logger log15.Logger) gentle.Logger {
+	return &Log15Adapter{
+		Logger: logger,
+	}
+}
+
+func (l *Log15Adapter) New(fields ...interface{}) gentle.Logger {
+	return &Log15Adapter{
+		Logger: l.Logger.New(fields...),
+	}
+}

extra/log/logrus.go

@@ -0,0 +1,104 @@
+package log
+
+import (
+	"errors"
+	"gopkg.in/cfchou/go-gentle.v3/gentle"
+	"gopkg.in/sirupsen/logrus.v1"
+)
+
+var (
+	errNotEvenFields = errors.New("Number of log fields is not even")
+	errFieldType     = errors.New("Not valid log field type")
+)
+
+type LogrusAdapter struct {
+	*logrus.Entry
+}
+
+func NewLogusLogger(logger *logrus.Logger) gentle.Logger {
+	return &LogrusAdapter{
+		Entry: logrus.NewEntry(logger),
+	}
+}
+
+func toFields(fields ...interface{}) (logrus.Fields, error) {
+	if len(fields)%2 != 0 {
+		return nil, errNotEvenFields
+	}
+	fs := logrus.Fields{}
+	for i := 0; i < len(fields); i += 2 {
+		k, ok := fields[i].(string)
+		if !ok {
+			return nil, errFieldType
+		}
+		fs[k] = fields[i+1]
+	}
+	return fs, nil
+}
+
+func (l *LogrusAdapter) Debug(msg string, fields ...interface{}) {
+	if fs, err := toFields(fields...); err != nil {
+		l.WithFields(logrus.Fields{
+			"origMsg": msg,
+		}).Error(err)
+	} else {
+		l.WithFields(fs).Debug(msg)
+	}
+}
+
+func (l *LogrusAdapter) Info(msg string, fields ...interface{}) {
+	if fs, err := toFields(fields...); err != nil {
+		l.WithFields(logrus.Fields{
+			"origMsg": msg,
+		}).Error(err)
+	} else {
+		l.WithFields(fs).Info(msg)
+	}
+}
+
+func (l *LogrusAdapter) Warn(msg string, fields ...interface{}) {
+	if fs, err := toFields(fields...); err != nil {
+		l.WithFields(logrus.Fields{
+			"origMsg": msg,
+		}).Error(err)
+	} else {
+		l.WithFields(fs).Warn(msg)
+	}
+}
+
+func (l *LogrusAdapter) Error(msg string, fields ...interface{}) {
+	if fs, err := toFields(fields...); err != nil {
+		l.WithFields(logrus.Fields{
+			"origMsg": msg,
+		}).Error(err)
+	} else {
+		l.WithFields(fs).Error(msg)
+	}
+}
+
+func (l *LogrusAdapter) Crit(msg string, fields ...interface{}) {
+	if fs, err := toFields(fields...); err != nil {
+		l.WithFields(logrus.Fields{
+			"origMsg": msg,
+		}).Error(err)
+	} else {
+		l.WithFields(fs).Fatal(msg)
+	}
+}
+
+func (l *LogrusAdapter) New(fields ...interface{}) gentle.Logger {
+	if fs, err := toFields(fields...); err != nil {
+		l.WithFields(logrus.Fields{
+			"err": err,
+		}).Error("Logger.New() with invalid fields")
+		return &LogrusAdapter{
+			// a new Entry with no new Fields
+			//Entry: logrus.WithFields(logrus.Fields{}),
+			Entry: logrus.NewEntry(l.Entry.Logger),
+		}
+	} else {
+		return &LogrusAdapter{
+			Entry: logrus.NewEntry(l.Entry.Logger).WithFields(fs),
+		}
+	}
+}

extra/metric/doc.go

@@ -0,0 +1,6 @@
+/*
+Package metric contains adaptors of metrics collectors used for
+gentle-ments in gentle. Currently prometheus and statsd are supported.
+
+*/
+package metric