add tracing-api

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.9-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.5-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

readme.md

@@ -33,12 +33,12 @@ try {
 }
 ```
 
-The `tracing` library can be used independently of `conjure-java-jaxrs-client` or `conjure-java-retrofit2-client`:
+Example of how to use the `tracing` library:
 
 ```groovy
 // build.gradle
 dependencies {
-  compile "com.palantir.conjure.java.runtime:tracing:$version"
+  compile "com.palantir.tracing:tracing:$version"
 }
 ```
 ```java

settings.gradle

@@ -1,6 +1,7 @@
 rootProject.name = 'tracing-java'
 
 include 'tracing'
+include 'tracing-api'
 include 'tracing-jaxrs'
 include 'tracing-okhttp3'
 include 'tracing-jersey'

tracing-api/build.gradle

@@ -0,0 +1,14 @@
+apply plugin: "org.inferred.processors"
+
+apply from: "$rootDir/gradle/publish-jar.gradle"
+
+dependencies {
+    compile "com.fasterxml.jackson.core:jackson-databind"
+
+    testCompile "junit:junit"
+    testCompile "org.assertj:assertj-core"
+    testCompile "org.mockito:mockito-core"
+    testCompile "com.fasterxml.jackson.dataformat:jackson-dataformat-yaml"
+
+    processor "org.immutables:value"
+}

tracing-api/src/main/java/com/palantir/tracing/api/OpenSpan.java

@@ -0,0 +1,79 @@
+/*
+ * (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.tracing.api;
+
+import java.util.Optional;
+import org.immutables.value.Value;
+
+/**
+ * A value object represented an open (i.e., non-completed) span. Once completed, the span is represented by a {@link
+ * Span} object.
+ */
+@Value.Immutable
+@Value.Style(visibility = Value.Style.ImplementationVisibility.PACKAGE)
+public abstract class OpenSpan {
+
+    /**
+     * Returns a description of the operation for this event.
+     */
+    public abstract String getOperation();
+
+    /**
+     * Returns the start time in microseconds since epoch start of the span represented by this state.
+     * <p>
+     * Users of this class should not set this value manually in the builder, it is configured automatically when using
+     * the {@link #builder()} static.
+     */
+    public abstract long getStartTimeMicroSeconds();
+
+    /**
+     * Returns the starting clock position in nanoseconds for use in computing span duration.
+     * <p>
+     * Users of this class should not set this value manually in the builder, it is configured automatically when using
+     * the {@link #builder()} static.
+     */
+    public abstract long getStartClockNanoSeconds();
+
+    /**
+     * Returns the identifier of the parent span for the current span, if one exists.
+     */
+    public abstract Optional<String> getParentSpanId();
+
+    /**
+     * Returns a globally unique identifier representing a single span within the call trace.
+     */
+    public abstract String getSpanId();
+
+    /** Indicates the {@link SpanType} of this span, e.g., a server-side vs. client-side vs local span. */
+    public abstract SpanType type();
+
+    /**
+     * Indicates if this trace state was sampled public abstract boolean isSampled();
+     * <p>
+     * /** Returns a builder for {@link OpenSpan} pre-initialized to use the current time.
+     * <p>
+     * Users should not set the {@code startTimeMs} value manually.
+     */
+    public static Builder builder() {
+        return new Builder()
+                // TODO(rfink): Use direct access to system microseconds when moving to Java8 / Java9
+                .startTimeMicroSeconds(System.currentTimeMillis() * 1000)
+                .startClockNanoSeconds(System.nanoTime());
+    }
+
+    public static class Builder extends ImmutableOpenSpan.Builder {}
+}

tracing-api/src/main/java/com/palantir/tracing/api/Span.java

@@ -0,0 +1,53 @@
+/*
+ * (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.tracing.api;
+
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import java.util.Map;
+import java.util.Optional;
+import org.immutables.value.Value;
+
+/**
+ * A value class representing a completed Span, see {@link OpenSpan} for a description of the fields.
+ */
+@JsonDeserialize(as = ImmutableSpan.class)
+@JsonSerialize(as = ImmutableSpan.class)
+@Value.Immutable
+@Value.Style(visibility = Value.Style.ImplementationVisibility.PACKAGE)
+public abstract class Span {
+
+    public abstract String getTraceId();
+    public abstract Optional<String> getParentSpanId();
+    public abstract String getSpanId();
+    public abstract SpanType type();
+    public abstract String getOperation();
+    public abstract long getStartTimeMicroSeconds();
+    public abstract long getDurationNanoSeconds();
+    /**
+     * Returns a map of custom key-value metadata with which spans will be annotated. For example, a "userId" key could
+     * be added to associate spans with the requesting user.
+     */
+    public abstract Map<String, String> getMetadata();
+
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    public static class Builder extends ImmutableSpan.Builder {}
+
+}

tracing-api/src/main/java/com/palantir/tracing/api/SpanObserver.java

@@ -0,0 +1,25 @@
+/*
+ * (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.tracing.api;
+
+/**
+ * Represents the event receiver for span completion events. Implementations are invoked synchronously on the primary
+ * execution thread, and as a result must execute quickly.
+ */
+public interface SpanObserver {
+    void consume(Span span);
+}

tracing-api/src/main/java/com/palantir/tracing/api/SpanType.java

@@ -0,0 +1,34 @@
+/*
+ * (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.tracing.api;
+
+public enum SpanType {
+    /**
+     * Indicates that this span encapsulates server-side work of an RPC call. This is typically the outermost span of a
+     * set of calls made within one service as a result of an incoming RPC call.
+     */
+    SERVER_INCOMING,
+
+    /**
+     * Indicates that this is the innermost span encapsulating remote work, typically the last span opened by an RPC
+     * client.
+     */
+    CLIENT_OUTGOING,
+
+    /** Indicates a local method call or computation that does not involve RPC. */
+    LOCAL
+}

tracing-api/src/main/java/com/palantir/tracing/api/TraceHttpHeaders.java

@@ -0,0 +1,25 @@
+/*
+ * (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.palantir.tracing.api;
+
+/** Zipkin-compatible HTTP header names. */
+public interface TraceHttpHeaders {
+    String TRACE_ID = "X-B3-TraceId";
+    String PARENT_SPAN_ID = "X-B3-ParentSpanId";
+    String SPAN_ID = "X-B3-SpanId";
+    String IS_SAMPLED = "X-B3-Sampled";
+}

tracing-api/versions.lock

@@ -0,0 +1,36 @@
+{
+    "compileClasspath": {
+        "com.fasterxml.jackson.core:jackson-annotations": {
+            "locked": "2.9.5",
+            "transitive": [
+                "com.fasterxml.jackson.core:jackson-databind"
+            ]
+        },
+        "com.fasterxml.jackson.core:jackson-core": {
+            "locked": "2.9.5",
+            "transitive": [
+                "com.fasterxml.jackson.core:jackson-databind"
+            ]
+        },
+        "com.fasterxml.jackson.core:jackson-databind": {
+            "locked": "2.9.5"
+        }
+    },
+    "runtime": {
+        "com.fasterxml.jackson.core:jackson-annotations": {
+            "locked": "2.9.5",
+            "transitive": [
+                "com.fasterxml.jackson.core:jackson-databind"
+            ]
+        },
+        "com.fasterxml.jackson.core:jackson-core": {
+            "locked": "2.9.5",
+            "transitive": [
+                "com.fasterxml.jackson.core:jackson-databind"
+            ]
+        },
+        "com.fasterxml.jackson.core:jackson-databind": {
+            "locked": "2.9.5"
+        }
+    }
+}

tracing-jaxrs/versions.lock

@@ -21,8 +21,8 @@
                 "com.fasterxml.jackson.datatype:jackson-datatype-guava",
                 "com.fasterxml.jackson.datatype:jackson-datatype-jdk8",
                 "com.fasterxml.jackson.module:jackson-module-afterburner",
-                "com.palantir.conjure.java.api:tracing",
-                "com.palantir.tracing:tracing"
+                "com.palantir.tracing:tracing",
+                "com.palantir.tracing:tracing-api"
             ]
         },
         "com.fasterxml.jackson.datatype:jackson-datatype-guava": {
@@ -50,12 +50,6 @@
                 "com.palantir.tracing:tracing"
             ]
         },
-        "com.palantir.conjure.java.api:tracing": {
-            "locked": "2.0.0-rc3",
-            "transitive": [
-                "com.palantir.tracing:tracing"
-            ]
-        },
         "com.palantir.safe-logging:safe-logging": {
             "locked": "1.3.0",
             "transitive": [
@@ -65,6 +59,12 @@
         "com.palantir.tracing:tracing": {
             "project": true
         },
+        "com.palantir.tracing:tracing-api": {
+            "project": true,
+            "transitive": [
+                "com.palantir.tracing:tracing"
+            ]
+        },
         "javax.ws.rs:javax.ws.rs-api": {
             "locked": "2.0.1"
         },
@@ -97,8 +97,8 @@
                 "com.fasterxml.jackson.datatype:jackson-datatype-guava",
                 "com.fasterxml.jackson.datatype:jackson-datatype-jdk8",
                 "com.fasterxml.jackson.module:jackson-module-afterburner",
-                "com.palantir.conjure.java.api:tracing",
-                "com.palantir.tracing:tracing"
+                "com.palantir.tracing:tracing",
+                "com.palantir.tracing:tracing-api"
             ]
         },
         "com.fasterxml.jackson.datatype:jackson-datatype-guava": {
@@ -126,12 +126,6 @@
                 "com.palantir.tracing:tracing"
             ]
         },
-        "com.palantir.conjure.java.api:tracing": {
-            "locked": "2.0.0-rc3",
-            "transitive": [
-                "com.palantir.tracing:tracing"
-            ]
-        },
         "com.palantir.safe-logging:safe-logging": {
             "locked": "1.3.0",
             "transitive": [
@@ -141,6 +135,12 @@
         "com.palantir.tracing:tracing": {
             "project": true
         },
+        "com.palantir.tracing:tracing-api": {
+            "project": true,
+            "transitive": [
+                "com.palantir.tracing:tracing"
+            ]
+        },
         "javax.ws.rs:javax.ws.rs-api": {
             "locked": "2.0.1"
         },

tracing-jersey/src/main/java/com/palantir/tracing/jersey/TraceEnrichingFilter.java

@@ -17,11 +17,11 @@
 package com.palantir.tracing.jersey;
 
 import com.google.common.base.Strings;
-import com.palantir.conjure.java.api.tracing.Span;
-import com.palantir.conjure.java.api.tracing.SpanType;
-import com.palantir.conjure.java.api.tracing.TraceHttpHeaders;
 import com.palantir.tracing.Tracer;
 import com.palantir.tracing.Tracers;
+import com.palantir.tracing.api.Span;
+import com.palantir.tracing.api.SpanType;
+import com.palantir.tracing.api.TraceHttpHeaders;
 import java.io.IOException;
 import java.util.Optional;
 import javax.ws.rs.container.ContainerRequestContext;