From 4ed46cec39049da48b2056ed288cd30d52218750 Mon Sep 17 00:00:00 2001
From: Guillaume Polaert <gpolaert@gmail.com>
Date: Thu, 27 Jul 2017 10:48:35 +0200
Subject: [PATCH] use millis precision + javadoc

---
 .../java/com/datadoghq/trace/DDBaseSpan.java  |  3 +--
 .../java/com/datadoghq/trace/util/Clock.java  | 23 +++++++++++++++++++
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/dd-trace/src/main/java/com/datadoghq/trace/DDBaseSpan.java b/dd-trace/src/main/java/com/datadoghq/trace/DDBaseSpan.java
index 865b0c9e6f..db48f77b4a 100644
--- a/dd-trace/src/main/java/com/datadoghq/trace/DDBaseSpan.java
+++ b/dd-trace/src/main/java/com/datadoghq/trace/DDBaseSpan.java
@@ -46,8 +46,7 @@ public abstract class DDBaseSpan<S extends BaseSpan> implements BaseSpan<S> {
   }
 
   public final void finish() {
-    this.durationNano = Clock.currentNanoTicks() - startTimeNano;
-    afterFinish();
+    finish(Clock.currentMicroTime() - startTimeMicro);
   }
 
   public final void finish(final long stoptimeMicros) {
diff --git a/dd-trace/src/main/java/com/datadoghq/trace/util/Clock.java b/dd-trace/src/main/java/com/datadoghq/trace/util/Clock.java
index ba50458bab..dc8f456297 100644
--- a/dd-trace/src/main/java/com/datadoghq/trace/util/Clock.java
+++ b/dd-trace/src/main/java/com/datadoghq/trace/util/Clock.java
@@ -2,12 +2,35 @@ package com.datadoghq.trace.util;
 
 import java.util.concurrent.TimeUnit;
 
+/**
+ * A simple wrapper for system clock that aims to provide the current time
+ *
+ * <p>
+ *
+ * <p>The JDK provides two clocks:
+ * <li>one in nanoseconds, for precision, but it can only use to measure durations
+ * <li>one in milliseconds, for accuracy, useful to provide epoch time
+ *     <p>
+ *     <p>At this time, we are using a millis precision (converted to micros) in order to guarantee
+ *     consistency between the span start times and the durations
+ */
 public class Clock {
 
+  /**
+   * Get the current nanos ticks, this method can't be use for date accuracy (only duration
+   * calculations)
+   *
+   * @return The current nanos ticks
+   */
   public static synchronized long currentNanoTicks() {
     return System.nanoTime();
   }
 
+  /**
+   * Get the current time in micros. The actual precision is the millis
+   *
+   * @return the current epoch time in micros
+   */
   public static synchronized long currentMicroTime() {
     return TimeUnit.MILLISECONDS.toMicros(System.currentTimeMillis());
   }