From b62d797a8d78a41902a3beb2bc1acd008752c145 Mon Sep 17 00:00:00 2001
From: Kai Ren <tyranron@gmail.com>
Date: Thu, 8 Mar 2018 17:41:28 +0200
Subject: [PATCH] Mention fields duplication caveat in documentation (#41)

---
 README.md  | 15 +++++++++++++++
 context.go |  2 ++
 event.go   |  3 +++
 log.go     | 14 ++++++++++++++
 4 files changed, 34 insertions(+)

diff --git a/README.md b/README.md
index 76c51b8..7a034b4 100644
--- a/README.md
+++ b/README.md
@@ -476,3 +476,18 @@ Log a static string, without any context or `printf`-style templating:
 | logrus | 1244 ns/op | 1505 B/op | 27 allocs/op |
 | apex/log | 2751 ns/op | 584 B/op | 11 allocs/op |
 | log15 | 5181 ns/op | 1592 B/op | 26 allocs/op |
+
+## Caveats
+
+There is no fields deduplication out-of-the-box.
+Using the same key multiple times creates new key in final JSON each time.
+
+```go
+logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
+logger.Info().
+       Timestamp().
+       Msg("dup")
+// Output: {"level":"info","time":1494567715,"time":1494567715,"message":"dup"}
+```
+
+However, it’s not a big deal though as JSON accepts dup keys, the last one prevails.
diff --git a/context.go b/context.go
index 7e86ea1..26f8a2a 100644
--- a/context.go
+++ b/context.go
@@ -277,6 +277,8 @@ var th = timestampHook{}
 
 // Timestamp adds the current local time as UNIX timestamp to the logger context with the "time" key.
 // To customize the key name, change zerolog.TimestampFieldName.
+//
+// NOTE: It won't dedupe the "time" key if the *Context has one already.
 func (c Context) Timestamp() Context {
 	c.l = c.l.Hook(th)
 	return c
diff --git a/event.go b/event.go
index d49bea4..13358e1 100644
--- a/event.go
+++ b/event.go
@@ -499,6 +499,9 @@ func (e *Event) Floats64(key string, f []float64) *Event {
 
 // Timestamp adds the current local time as UNIX timestamp to the *Event context with the "time" key.
 // To customize the key name, change zerolog.TimestampFieldName.
+//
+// NOTE: It won't dedupe the "time" key if the *Event (or *Context) has one
+// already.
 func (e *Event) Timestamp() *Event {
 	if e == nil {
 		return e
diff --git a/log.go b/log.go
index 843a94b..9a73f80 100644
--- a/log.go
+++ b/log.go
@@ -82,6 +82,20 @@
 //     log.Warn().Msg("")
 //     // Output: {"level":"warn","severity":"warn"}
 //
+//
+// Caveats
+//
+// There is no fields deduplication out-of-the-box.
+// Using the same key multiple times creates new key in final JSON each time.
+//
+//     logger := zerolog.New(os.Stderr).With().Timestamp().Logger()
+//     logger.Info().
+//            Timestamp().
+//            Msg("dup")
+//     // Output: {"level":"info","time":1494567715,"time":1494567715,"message":"dup"}
+//
+// However, it’s not a big deal though as JSON accepts dup keys,
+// the last one prevails.
 package zerolog
 
 import (