Updates to Spring Boot 1.3 and upstream 1.25

* Adds duration and lookback queries
* Added docs for all core datatypes
* Uses "on duplicate key update" to merge late arriving span metadata
* Adds gzip compression of api traffic
* Adds clock skew adjustment

README.md

@@ -1,9 +1,15 @@
 # zipkin-java
 Experimental java zipkin backend. Please look at issues as we are currently working on scope.
 
+## Server
+You can run the experimental server to power the zipkin web UI.
 
-## Docker
-You can run the experimental docker server to power the zipkin web UI. The following is a hack of the [docker-zipkin](https://github.com/openzipkin/docker-zipkin) docker-compose instructions.
+```bash
+$ (cd zipkin-java-server; mvn spring-boot:run)
+```
+
+### Docker  
+You can also run the java server with docker. The following is a hack of the [docker-zipkin](https://github.com/openzipkin/docker-zipkin) docker-compose instructions.
 
 ```bash
 # build zipkin-java-server/target/zipkin-java-server-0.1.0-SNAPSHOT.jar

docker-compose.yml

@@ -13,7 +13,7 @@
 #
 
 mysql:
-  image: openzipkin/zipkin-mysql:1.21.1
+  image: openzipkin/zipkin-mysql:1.25.0
   ports:
     - 3306:3306
 query:
@@ -27,7 +27,7 @@ query:
   links:
     - mysql:storage
 web:
-  image: openzipkin/zipkin-web:1.21.1
+  image: openzipkin/zipkin-web:1.25.0
   ports:
     - 8080:8080
   environment:

pom.xml

@@ -54,13 +54,13 @@
     <maven-javadoc-plugin.version>2.10.3</maven-javadoc-plugin.version>
     <maven-license-plugin.version>2.11</maven-license-plugin.version>
     <maven-jar-plugin.version>2.6</maven-jar-plugin.version>
-    <maven-release-plugin.version>2.5.2</maven-release-plugin.version>
-    <maven-shade-plugin.version>2.4.1</maven-shade-plugin.version>
+    <maven-release-plugin.version>2.5.3</maven-release-plugin.version>
+    <maven-shade-plugin.version>2.4.2</maven-shade-plugin.version>
     <nexus-staging-maven-plugin.version>1.6.6</nexus-staging-maven-plugin.version>
     <maven-gpg-plugin.version>1.6</maven-gpg-plugin.version>
     <moshi.version>1.0.0</moshi.version>
     <okio.version>1.6.0</okio.version>
-    <spring-boot.version>1.2.7.RELEASE</spring-boot.version>
+    <spring-boot.version>1.3.0.RELEASE</spring-boot.version>
     <libthrift.version>0.9.3</libthrift.version>
   </properties>
 
@@ -187,6 +187,7 @@
       <scope>test</scope>
     </dependency>
   </dependencies>
+
   <build>
     <pluginManagement>
       <plugins>

zipkin-java-core/src/main/java/io/zipkin/Annotation.java

@@ -20,27 +20,29 @@
 import static io.zipkin.internal.Util.equal;
 
 /**
- * The endpoint associated with this annotation depends on {@link #value}.
+ * Associates an event that explains latency with a timestamp.
  *
- * <p/>When {@link #value} is...
- * <ul>
- *   <li>{@link Constants#CLIENT_ADDR}, this is the client endpoint of an RPC call</li>
- *   <li>{@link Constants#SERVER_ADDR}, this is the server endpoint of an RPC call</li>
- *   <li>Otherwise, this is the endpoint that recorded this annotation</li>
- * </ul>
+ * <p/>Unlike log statements, annotations are often codes: Ex. {@link Constants#SERVER_RECV "sr"}.
  */
 public final class Annotation implements Comparable<Annotation> {
 
   public static Annotation create(long timestamp, String value, @Nullable Endpoint endpoint) {
     return new Annotation(timestamp, value, endpoint);
   }
 
-  /** Microseconds from epoch */
+  /**
+   * Microseconds from epoch.
+   *
+   * <p/>This value should be set directly by instrumentation, using the most precise value
+   * possible. For example, {@code gettimeofday} or syncing {@link System#nanoTime} against a tick
+   * of {@link System#currentTimeMillis}.
+   */
   public final long timestamp;
 
-  /** What happened at the timestamp? */
+  /** Usually a short tag indicating an event, like {@link Constants#SERVER_RECV "sr"}. or "finagle.retry" */
   public final String value;
 
+  /** The host that recorded {@link #value}, primarily for query by service name. */
   @Nullable
   public final Endpoint endpoint;
 
@@ -64,17 +66,20 @@ public Builder(Annotation source) {
       this.endpoint = source.endpoint;
     }
 
-    public Annotation.Builder timestamp(long timestamp) {
+    /** @see Annotation#timestamp */
+    public Builder timestamp(long timestamp) {
       this.timestamp = timestamp;
       return this;
     }
 
-    public Annotation.Builder value(String value) {
+    /** @see Annotation#value */
+    public Builder value(String value) {
       this.value = value;
       return this;
     }
 
-    public Annotation.Builder endpoint(Endpoint endpoint) {
+    /** @see Annotation#endpoint */
+    public Builder endpoint(Endpoint endpoint) {
       this.endpoint = endpoint;
       return this;
     }
@@ -115,11 +120,12 @@ public int hashCode() {
     return h;
   }
 
+  /** Compares by {@link #timestamp}, then {@link #value}. */
   @Override
   public int compareTo(Annotation that) {
-    if (this == that) {
-      return 0;
-    }
-    return Long.compare(timestamp, that.timestamp);
+    if (this == that) return 0;
+    int byTimestamp = Long.compare(timestamp, that.timestamp);
+    if (byTimestamp != 0) return byTimestamp;
+    return value.compareTo(that.value);
   }
 }

zipkin-java-core/src/main/java/io/zipkin/BinaryAnnotation.java

@@ -15,15 +15,42 @@
 
 import io.zipkin.internal.JsonCodec;
 import io.zipkin.internal.Nullable;
+import io.zipkin.internal.Util;
 import java.util.Arrays;
 
 import static io.zipkin.internal.Util.checkNotNull;
 import static io.zipkin.internal.Util.equal;
 
+/**
+ * Binary annotations are tags applied to a Span to give it context. For example, a binary
+ * annotation of "http.uri" could the path to a resource in a RPC call.
+ *
+ * <p/>Binary annotations of type {@link Type#STRING} are always queryable, though more a historical
+ * implementation detail than a structural concern.
+ *
+ * <p/>Binary annotations can repeat, and vary on the host. Similar to Annotation, the host
+ * indicates who logged the event. This allows you to tell the difference between the client and
+ * server side of the same key. For example, the key "http.uri" might be different on the client and
+ * server side due to rewriting, like "/api/v1/myresource" vs "/myresource. Via the host field, you
+ * can see the different points of view, which often help in debugging.
+ */
 public final class BinaryAnnotation {
 
+  /** A subset of thrift base types, except BYTES. */
   public enum Type {
-    BOOL(0), BYTES(1), I16(2), I32(3), I64(4), DOUBLE(5), STRING(6);
+    /**
+     * Set to 0x01 when {@link BinaryAnnotation#key} is {@link Constants#CLIENT_ADDR} or  {@link
+     * Constants#SERVER_ADDR}
+     */
+    BOOL(0),
+    /** No encoding, or type is unknown. */
+    BYTES(1),
+    I16(2),
+    I32(3),
+    I64(4),
+    DOUBLE(5),
+    /** The only type zipkin v1 supports search against. */
+    STRING(6);
 
     public final int value;
 
@@ -54,17 +81,50 @@ public static Type fromValue(int value) {
     }
   }
 
+  /**
+   * Special-cased form supporting {@link Constants#CLIENT_ADDR} and
+   * {@link Constants#SERVER_ADDR}.
+   *
+   * @param key {@link Constants#CLIENT_ADDR} or {@link Constants#SERVER_ADDR}
+   * @param endpoint associated endpoint.
+   */
+  public static BinaryAnnotation address(String key, Endpoint endpoint) {
+    return new BinaryAnnotation(key, new byte[]{1}, Type.BOOL, checkNotNull(endpoint, "endpoint"));
+  }
+
+  /** String values are the only queryable type of binary annotation. */
+  public static BinaryAnnotation create(String key, String value, @Nullable Endpoint endpoint) {
+    return new BinaryAnnotation(key, value.getBytes(Util.UTF_8), Type.STRING, endpoint);
+  }
+
   public static BinaryAnnotation create(String key, byte[] value, Type type, @Nullable Endpoint endpoint) {
     return new BinaryAnnotation(key, value, type, endpoint);
   }
 
+  /**
+   * Name used to lookup spans, such as "http.uri" or "finagle.version".
+   */
   public final String key;
-
+  /**
+   * Serialized thrift bytes, in TBinaryProtocol format.
+   *
+   * <p/>For legacy reasons, byte order is big-endian. See THRIFT-3217.
+   */
   public final byte[] value;
-
+  /**
+   * The thrift type of value, most often STRING.
+   *
+   * <p/>Note: type shouldn't vary for the same key.
+   */
   public final Type type;
 
-  /** The endpoint that recorded this annotation */
+  /**
+   * The host that recorded {@link #value}, allowing query by service name or address.
+   *
+   * <p/>There are two exceptions: when {@link #key} is {@link Constants#CLIENT_ADDR} or {@link
+   * Constants#SERVER_ADDR}, this is the source or destination of an RPC. This exception allows
+   * zipkin to display network context of uninstrumented services, such as browsers or databases.
+   */
   @Nullable
   public final Endpoint endpoint;
 
@@ -91,23 +151,26 @@ public Builder(BinaryAnnotation source) {
       this.endpoint = source.endpoint;
     }
 
+    /** @see BinaryAnnotation#key */
     public BinaryAnnotation.Builder key(String key) {
       this.key = key;
       return this;
     }
 
+    /** @see BinaryAnnotation#value */
     public BinaryAnnotation.Builder value(byte[] value) {
       this.value = value.clone();
       return this;
     }
 
-    public BinaryAnnotation.Builder type(Type type) {
+    /** @see BinaryAnnotation#type */
+    public Builder type(Type type) {
       this.type = type;
       return this;
     }
 
-    @Nullable
-    public BinaryAnnotation.Builder endpoint(Endpoint endpoint) {
+    /** @see BinaryAnnotation#endpoint */
+    public BinaryAnnotation.Builder endpoint(@Nullable Endpoint endpoint) {
       this.endpoint = endpoint;
       return this;
     }