Add some more doc

README.md

@@ -45,7 +45,7 @@ log.Fatal().
 // Exit 1
 ```
 
-NOTE: Using `Msgf` generates an allocation even when the logger is disabled.
+NOTE: Using `Msgf` generates one allocation even when the logger is disabled.
 
 ### Fields can be added to log messages
 
@@ -147,7 +147,7 @@ sampled.Info().Msg("will be logged every 10 messages")
 ### Pass a sub-logger by context
 
 ```go
-ctx := log.With("component", "module").Logger().FromContext(ctx)
+ctx := log.With("component", "module").Logger().WithContext(ctx)
 
 log.Ctx(ctx).Info().Msg("hello world")
 
@@ -162,6 +162,7 @@ In this example we use [alice](github.com/justinas/alice) to install logger for
 
 ```go
 log := zerolog.New(os.Stdout).With().
+    Timestamp().
     Str("role", "my-service").
     Str("host", host).
     Logger()
@@ -187,6 +188,8 @@ h := c.Then(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
         Str("user", "current user").
         Str("status", "ok").
         Msg("Something happend")
+
+    // Output: {"level":"info","time":"2001-02-03T04:05:06Z","role":"my-service","host":"local-hostname","req_id":"b4g0l5t6tfid6dtrapu0","user":"current user","status":"ok","message":"Something happend"}
 }))
 http.Handle("/", h)
 

field.go

@@ -7,8 +7,6 @@ import (
 	"time"
 )
 
-var now = time.Now
-
 func appendKey(dst []byte, key string) []byte {
 	if len(dst) > 1 {
 		dst = append(dst, ',')
@@ -85,7 +83,7 @@ func appendTime(dst []byte, key string, t time.Time) []byte {
 }
 
 func appendTimestamp(dst []byte) []byte {
-	return appendTime(dst, TimestampFieldName, now())
+	return appendTime(dst, TimestampFieldName, TimestampFunc())
 }
 
 func appendDuration(dst []byte, key string, d, unit time.Duration, float bool) []byte {

globals.go

@@ -23,6 +23,9 @@ var (
 	// If set to an empty string, the time is formatted as an UNIX timestamp
 	// as integer.
 	TimeFieldFormat = time.RFC3339
+
+	// TimestampFunc defines the function called to generate a timestamp.
+	TimestampFunc = time.Now
 )
 
 var (

hlog/hlog_example_test.go

@@ -3,22 +3,42 @@ package hlog_test
 import (
 	"net/http"
 	"os"
+	"time"
+
+	"net/http/httptest"
 
 	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/hlog"
 )
 
 // fake alice to avoid dep
-type alice struct{}
+type middleware func(http.Handler) http.Handler
+type alice struct {
+	m []middleware
+}
 
-func (a alice) Append(interface{}) alice       { return a }
-func (alice) Then(h http.Handler) http.Handler { return h }
+func (a alice) Append(m middleware) alice {
+	a.m = append(a.m, m)
+	return a
+}
+func (a alice) Then(h http.Handler) http.Handler {
+	for i := range a.m {
+		h = a.m[len(a.m)-1-i](h)
+	}
+	return h
+}
+
+func init() {
+	zerolog.TimestampFunc = func() time.Time {
+		return time.Date(2001, time.February, 3, 4, 5, 6, 7, time.UTC)
+	}
+}
 
 func Example_handler() {
-	host, _ := os.Hostname()
 	log := zerolog.New(os.Stdout).With().
+		Timestamp().
 		Str("role", "my-service").
-		Str("host", host).
+		Str("host", "local-hostname").
 		Logger()
 
 	c := alice{}
@@ -31,7 +51,7 @@ func Example_handler() {
 	c = c.Append(hlog.RemoteAddrHandler("ip"))
 	c = c.Append(hlog.UserAgentHandler("user_agent"))
 	c = c.Append(hlog.RefererHandler("referer"))
-	c = c.Append(hlog.RequestIDHandler("req_id", "Request-Id"))
+	//c = c.Append(hlog.RequestIDHandler("req_id", "Request-Id"))
 
 	// Here is your final handler
 	h := c.Then(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -45,7 +65,7 @@ func Example_handler() {
 	}))
 	http.Handle("/", h)
 
-	if err := http.ListenAndServe(":8080", nil); err != nil {
-		log.Fatal().Err(err).Msg("Startup failed")
-	}
+	h.ServeHTTP(httptest.NewRecorder(), &http.Request{})
+
+	// Output: {"level":"info","time":"2001-02-03T04:05:06Z","role":"my-service","host":"local-hostname","user":"current user","status":"ok","message":"Something happend"}
 }

log_test.go

@@ -237,11 +237,11 @@ func TestLevelWriter(t *testing.T) {
 }
 
 func TestContextTimestamp(t *testing.T) {
-	now = func() time.Time {
+	TimestampFunc = func() time.Time {
 		return time.Date(2001, time.February, 3, 4, 5, 6, 7, time.UTC)
 	}
 	defer func() {
-		now = time.Now
+		TimestampFunc = time.Now
 	}()
 	out := &bytes.Buffer{}
 	log := New(out).With().Timestamp().Str("foo", "bar").Logger()
@@ -253,11 +253,11 @@ func TestContextTimestamp(t *testing.T) {
 }
 
 func TestEventTimestamp(t *testing.T) {
-	now = func() time.Time {
+	TimestampFunc = func() time.Time {
 		return time.Date(2001, time.February, 3, 4, 5, 6, 7, time.UTC)
 	}
 	defer func() {
-		now = time.Now
+		TimestampFunc = time.Now
 	}()
 	out := &bytes.Buffer{}
 	log := New(out).With().Str("foo", "bar").Logger()