Adds more insight into why following timestamp practice helps (#53)
* Adds more insight into why following timestamp practice helps
same question was raised by @fedj and @paolochiodi basically.. why should I?
This is an attempt to help folks make the right decisions. While adding timestamp
and duration is trivial, the reason why shouldn't be "cause you should" :)
diff --git a/pages/instrumenting.md b/pages/instrumenting.md
index 047f968..b7bdc4c 100644
--- a/pages/instrumenting.md
+++ b/pages/instrumenting.md
@@ -246,4 +246,21 @@
Span.timestamp and Span.duration are fields added in 2015, 3 years after Zipkin
started. Not all libraries log these. When these fields are not set, Zipkin adds
-them at query time.
+them at query time (not collection time); this is not ideal.
+
+The [duration query](http://zipkin.io/zipkin-api/#/paths/%252Ftraces/get/parameters/minDuration)
+will not work as there's no data to query. Also, local (in-process) spans aren't required
+to have annotations, so they cannot be queried unless their timestamp is set.
+
+When duration isn't set by instrumentation, Zipkin tries to derive duration at query time,
+it has to use the problematic method of timestamp math. Ex. if an NTP update happened inside
+the span, the duration Zipkin caculates will be wrong.
+
+Finally, there's a desire for many to move to single-host spans. The migration path
+towards this is to split dual-host RPC spans into two. When instrumentation logs timestamp
+only for spans it owns, splitting collectors have a heuristic to distinguish a server-initiated
+root span from a client-initiated, dual-host one.
+
+The bottom-line is that choosing not to record Span.timestamp and duration will result
+in less accurate data and less functionality. Since it is very easy to record these authoritatively
+before reporting, all Zipkin instrumentation should do it or ask someone to help them do it.
