Update README for zpages configuration. Add a generic class that registers all Handlers. (#555)

* Update README for zpages configuration. Add a generic class that registers all Handlers.

* renames and more tests.

* Update FAQ section in README.

* Fix second round of comments

8 files changed, 231 insertions, 74 deletions

diff --git a/contrib/zpages/README.md b/contrib/zpages/README.md
index 06cc7bcb..7660acd0 100644
--- a/contrib/zpages/README.md
+++ b/contrib/zpages/README.md
@@ -4,9 +4,48 @@
 The *OpenCensus Z-Pages for Java* is a collection of HTML pages to display stats and trace data and
 allows library configuration control.
 
+## Hello "Z-Pages"
+
+### Add the dependencies to your project
+
+For Maven add to your `pom.xml`:
+```xml
+<dependency>
+  <groupId>io.opencensus</groupId>
+  <artifactId>opencensus-contrib-zpages</artifactId>
+  <version>0.6.0</version>
+</dependency>
+```
+
+For Gradle add to your dependencies:
+```gradle
+compile 'io.opencensus:opencensus-contrib-zpages:0.6.0'
+```
+
+### Register the Z-Pages
+
+```java
+public class MyMainClass {
+  public static void main(String[] args) throws Exception {
+    // ...
+    HttpServer server = HttpServer.create(new InetSocketAddress(8000), 10);
+    ZPageHandlers.registerAllToHttpServer(server);
+    server.start();
+    // ...
+  }
+}
+```
+
+### FAQ
+
+#### Why do I not see sampled spans based on latency and error codes for a given span name?
+Sampled spans based on latency and error codes are available only for registered span names. 
+For more details see [SampledSpanStore][sampledspanstore-url].
+
 [travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master
 [travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java
 [appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true
 [appveyor-url]: https://ci.appveyor.com/project/instrumentationjavateam/opencensus-java/branch/master
 [maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-zpages/badge.svg
 [maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-zpages
+[sampledspanstore-url]: https://github.com/census-instrumentation/opencensus-java/blob/master/api/src/main/java/io/opencensus/trace/export/SampledSpanStore.java
diff --git a/contrib/zpages/src/main/java/io/opencensus/zpages/TracezPageFormatter.java b/contrib/zpages/src/main/java/io/opencensus/zpages/TracezZPageHandler.java
index 759dad78..cdeedb21 100644
--- a/contrib/zpages/src/main/java/io/opencensus/zpages/TracezPageFormatter.java
+++ b/contrib/zpages/src/main/java/io/opencensus/zpages/TracezZPageHandler.java
@@ -70,12 +70,8 @@ import javax.annotation.Nullable;
  *
  * <p>It prints a summary table which contains one row for each span name and data about number of
  * active and sampled spans.
- *
- * <p>See {@link TracezHttpHandler} for how to use the formatter with private HTTP server
- * implementations or how to use with {@link com.sun.net.httpserver.HttpServer}.
  */
-public final class TracezPageFormatter {
-
+final class TracezZPageHandler extends ZPageHandler {
   private enum RequestType {
     RUNNING(0),
     FINISHED(1),
@@ -107,6 +103,7 @@ public final class TracezPageFormatter {
     }
   }
 
+  private static final String TRACEZ_URL = "/tracez";
   private static final Tracer tracer = Tracing.getTracer();
   // Color to use for zebra-striping.
   private static final String ZEBRA_STRIPE_COLOR = "#eee";
@@ -124,30 +121,30 @@ public final class TracezPageFormatter {
   private final RunningSpanStore runningSpanStore;
   private final SampledSpanStore sampledSpanStore;
 
-  private TracezPageFormatter(
+  private TracezZPageHandler(
       @Nullable RunningSpanStore runningSpanStore, @Nullable SampledSpanStore sampledSpanStore) {
     this.runningSpanStore = runningSpanStore;
     this.sampledSpanStore = sampledSpanStore;
   }
 
   /**
-   * Constructs a new {@code TracezPageFormatter}.
+   * Constructs a new {@code TracezZPageHandler}.
    *
    * @param runningSpanStore the instance of the {@code RunningSpanStore} to be used.
    * @param sampledSpanStore the instance of the {@code SampledSpanStore} to be used.
-   * @return a new {@code TracezPageFormatter}.
+   * @return a new {@code TracezZPageHandler}.
    */
-  public static TracezPageFormatter create(
+  public static TracezZPageHandler create(
       @Nullable RunningSpanStore runningSpanStore, @Nullable SampledSpanStore sampledSpanStore) {
-    return new TracezPageFormatter(runningSpanStore, sampledSpanStore);
+    return new TracezZPageHandler(runningSpanStore, sampledSpanStore);
   }
 
-  /**
-   * Emits the HTML generated page to the {@code outputStream}.
-   *
-   * @param queryMap the query components map.
-   * @param outputStream the output {@code OutputStream}.
-   */
+  @Override
+  public String getUrlPath() {
+    return TRACEZ_URL;
+  }
+
+  @Override
   public void emitHtml(Map<String, String> queryMap, OutputStream outputStream) {
     PrintWriter out =
         new PrintWriter(new BufferedWriter(new OutputStreamWriter(outputStream, Charsets.UTF_8)));
diff --git a/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHandler.java b/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHandler.java
new file mode 100644
index 00000000..bd8cb082
--- /dev/null
+++ b/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHandler.java
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2017, OpenCensus Authors
+ *
+ * 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 io.opencensus.zpages;
+
+import java.io.OutputStream;
+import java.util.Map;
+
+/**
+ * Main interface for all the Z-Pages. All Z-Pages must implement this interface to allow other HTTP
+ * server implementation to support these pages.
+ */
+public abstract class ZPageHandler {
+
+  /**
+   * Returns the URL path that should be used to register this page.
+   *
+   * @return the URL path that should be used to register this page.
+   */
+  public abstract String getUrlPath();
+
+  /**
+   * Emits the HTML generated page to the {@code outputStream}.
+   *
+   * @param queryMap the query components map.
+   * @param outputStream the output {@code OutputStream}.
+   */
+  public abstract void emitHtml(Map<String, String> queryMap, OutputStream outputStream);
+
+  /**
+   * Package protected constructor to disallow users to extend this class.
+   */
+  ZPageHandler() {}
+}
diff --git a/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHandlers.java b/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHandlers.java
new file mode 100644
index 00000000..f8ca9f78
--- /dev/null
+++ b/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHandlers.java
@@ -0,0 +1,69 @@
+/*
+ * Copyright 2017, OpenCensus Authors
+ *
+ * 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 io.opencensus.zpages;
+
+import com.sun.net.httpserver.HttpServer;
+import io.opencensus.trace.Tracing;
+
+/**
+ * A collection of HTML pages to display stats and trace data and allow library configuration
+ * control.
+ *
+ * <p>Example usage with {@link HttpServer}:
+ *
+ * <pre>{@code
+ * public class Main {
+ *   public static void main(String[] args) throws Exception {
+ *     HttpServer server = HttpServer.create(new InetSocketAddress(8000), 10);
+ *     ZPageHandlers.registerAllToHttpServer(server);
+ *     server.start();
+ *     ... // do work
+ *   }
+ * }
+ * }</pre>
+ */
+public final class ZPageHandlers {
+  private static final ZPageHandler tracezZPageHandler =
+      TracezZPageHandler.create(
+          Tracing.getExportComponent().getRunningSpanStore(),
+          Tracing.getExportComponent().getSampledSpanStore());
+
+  /**
+   * Returns a {@code ZPageHandler} for tracing debug. The page displays information about all
+   * active spans and all sampled spans based on latency and errors.
+   *
+   * <p>It prints a summary table which contains one row for each span name and data about number of
+   * active and sampled spans.
+   *
+   * <p>If no sampled spans based on latency and error codes are available for a given name, make
+   * sure that the span name is registered to the {@code SampledSpanStore}.
+   */
+  public static ZPageHandler getTracezZPageHandler() {
+    return tracezZPageHandler;
+  }
+
+  /**
+   * Registers all pages to the given {@code HttpServer}.
+   *
+   * @param server the server that exports the tracez page.
+   */
+  public static void registerAllToHttpServer(HttpServer server) {
+    server.createContext(tracezZPageHandler.getUrlPath(), new ZPageHttpHandler(tracezZPageHandler));
+  }
+
+  private ZPageHandlers() {}
+}
diff --git a/contrib/zpages/src/main/java/io/opencensus/zpages/TracezHttpHandler.java b/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHttpHandler.java
index 48a6c940..cde7c78b 100644
--- a/contrib/zpages/src/main/java/io/opencensus/zpages/TracezHttpHandler.java
+++ b/contrib/zpages/src/main/java/io/opencensus/zpages/ZPageHttpHandler.java
@@ -20,12 +20,10 @@ import com.google.common.annotations.VisibleForTesting;
 import com.google.common.collect.ImmutableMap;
 import com.sun.net.httpserver.HttpExchange;
 import com.sun.net.httpserver.HttpHandler;
-import com.sun.net.httpserver.HttpServer;
 import io.opencensus.common.Scope;
 import io.opencensus.trace.AttributeValue;
 import io.opencensus.trace.Tracer;
 import io.opencensus.trace.Tracing;
-import io.opencensus.trace.export.ExportComponent;
 import java.io.IOException;
 import java.net.URI;
 import java.util.Arrays;
@@ -33,53 +31,27 @@ import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
 
-/**
- * An {@link HttpHandler} that displays information about active and sampled spans recorded using
- * the OpenCensus library.
- *
- * <p>Example usage with {@link HttpServer}:
- *
- * <pre>{@code
- * public class Main {
- *   public static void main(String[] args) throws Exception {
- *     HttpServer server = HttpServer.create(new InetSocketAddress(8000), 10);
- *     TracezHttpHandler.register(server);
- *     server.start();
- *   }
- * }
- * }</pre>
- */
-public final class TracezHttpHandler implements HttpHandler {
+/** An {@link HttpHandler} that can be used to render HTML pages using any {@code ZPageHandler}. */
+final class ZPageHttpHandler implements HttpHandler {
   private static final Tracer tracer = Tracing.getTracer();
-  private static final String TRACEZ_URL = "/tracez";
-  private static final String HTTP_SERVER_SPAN_NAME = "HttpServer/tracez";
-  private final TracezPageFormatter pageFormatter;
+  private static final String HTTP_SERVER = "HttpServer";
+  private final ZPageHandler zpageHandler;
+  private final String httpServerSpanName;
 
-  /** Constructs a new {@code TracezHttpHandler}. */
-  private TracezHttpHandler() {
-    ExportComponent exportComponent = Tracing.getExportComponent();
-    this.pageFormatter =
-        TracezPageFormatter.create(
-            exportComponent.getRunningSpanStore(), exportComponent.getSampledSpanStore());
+  /** Constructs a new {@code ZPageHttpHandler}. */
+  ZPageHttpHandler(ZPageHandler zpageHandler) {
+    this.zpageHandler = zpageHandler;
+    this.httpServerSpanName = HTTP_SERVER + zpageHandler.getUrlPath();
     Tracing.getExportComponent()
         .getSampledSpanStore()
-        .registerSpanNamesForCollection(Arrays.asList(HTTP_SERVER_SPAN_NAME));
-  }
-
-  /**
-   * Registers the tracez {@code HttpHandler} to the given {@code HttpServer}.
-   *
-   * @param server the server that exports the tracez page.
-   */
-  public static void register(HttpServer server) {
-    server.createContext(TRACEZ_URL, new TracezHttpHandler());
+        .registerSpanNamesForCollection(Arrays.asList(httpServerSpanName));
   }
 
   @Override
   public final void handle(HttpExchange httpExchange) throws IOException {
     try (Scope ss =
         tracer
-            .spanBuilderWithExplicitParent(HTTP_SERVER_SPAN_NAME, null)
+            .spanBuilderWithExplicitParent(httpServerSpanName, null)
             .setRecordEvents(true)
             .startScopedSpan()) {
       tracer
@@ -91,7 +63,7 @@ public final class TracezHttpHandler implements HttpHandler {
                       AttributeValue.stringAttributeValue(httpExchange.getRequestMethod()))
                   .build());
       httpExchange.sendResponseHeaders(200, 0);
-      pageFormatter.emitHtml(
+      zpageHandler.emitHtml(
           uriQueryToMap(httpExchange.getRequestURI()), httpExchange.getResponseBody());
     } finally {
       httpExchange.close();
diff --git a/contrib/zpages/src/test/java/io/opencensus/zpages/TracezPageFormatterTest.java b/contrib/zpages/src/test/java/io/opencensus/zpages/TracezZPageHandlerTest.java
index f937301d..ddda3d0c 100644
--- a/contrib/zpages/src/test/java/io/opencensus/zpages/TracezPageFormatterTest.java
+++ b/contrib/zpages/src/test/java/io/opencensus/zpages/TracezZPageHandlerTest.java
@@ -35,9 +35,9 @@ import org.junit.runners.JUnit4;
 import org.mockito.Mock;
 import org.mockito.MockitoAnnotations;
 
-/** Unit tests for {@link TracezPageFormatter}. */
+/** Unit tests for {@link TracezZPageHandler}. */
 @RunWith(JUnit4.class)
-public class TracezPageFormatterTest {
+public class TracezZPageHandlerTest {
   private static final String ACTIVE_SPAN_NAME = "TestActiveSpan";
   private static final String SAMPLED_SPAN_NAME = "TestSampledSpan";
   private static final String ACTIVE_SAMPLED_SPAN_NAME = "TestActiveAndSampledSpan";
@@ -74,11 +74,11 @@ public class TracezPageFormatterTest {
   @Test
   public void emitSummaryTableForEachSpan() {
     OutputStream output = new ByteArrayOutputStream();
-    TracezPageFormatter tracezPageFormatter =
-        TracezPageFormatter.create(runningSpanStore, sampledSpanStore);
+    TracezZPageHandler tracezZPageHandler =
+        TracezZPageHandler.create(runningSpanStore, sampledSpanStore);
     when(runningSpanStore.getSummary()).thenReturn(runningSpanStoreSummary);
     when(sampledSpanStore.getSummary()).thenReturn(sampledSpanStoreSummary);
-    tracezPageFormatter.emitHtml(Collections.emptyMap(), output);
+    tracezZPageHandler.emitHtml(Collections.emptyMap(), output);
     assertThat(output.toString()).contains(ACTIVE_SPAN_NAME);
     assertThat(output.toString()).contains(SAMPLED_SPAN_NAME);
     assertThat(output.toString()).contains(ACTIVE_SAMPLED_SPAN_NAME);
@@ -87,11 +87,11 @@ public class TracezPageFormatterTest {
   @Test
   public void linksForActiveRequests_InSummaryTable() {
     OutputStream output = new ByteArrayOutputStream();
-    TracezPageFormatter tracezPageFormatter =
-        TracezPageFormatter.create(runningSpanStore, sampledSpanStore);
+    TracezZPageHandler tracezZPageHandler =
+        TracezZPageHandler.create(runningSpanStore, sampledSpanStore);
     when(runningSpanStore.getSummary()).thenReturn(runningSpanStoreSummary);
     when(sampledSpanStore.getSummary()).thenReturn(sampledSpanStoreSummary);
-    tracezPageFormatter.emitHtml(Collections.emptyMap(), output);
+    tracezZPageHandler.emitHtml(Collections.emptyMap(), output);
     // 3 active requests
     assertThat(output.toString()).contains("href='?zspanname=TestActiveSpan&ztype=0&zsubtype=0'>3");
     // No active links
@@ -105,11 +105,11 @@ public class TracezPageFormatterTest {
   @Test
   public void linksForSampledRequests_InSummaryTable() {
     OutputStream output = new ByteArrayOutputStream();
-    TracezPageFormatter tracezPageFormatter =
-        TracezPageFormatter.create(runningSpanStore, sampledSpanStore);
+    TracezZPageHandler tracezZPageHandler =
+        TracezZPageHandler.create(runningSpanStore, sampledSpanStore);
     when(runningSpanStore.getSummary()).thenReturn(runningSpanStoreSummary);
     when(sampledSpanStore.getSummary()).thenReturn(sampledSpanStoreSummary);
-    tracezPageFormatter.emitHtml(Collections.emptyMap(), output);
+    tracezZPageHandler.emitHtml(Collections.emptyMap(), output);
     // No sampled links (ztype=1);
     assertThat(output.toString()).doesNotContain("href=\"?zspanname=TestActiveSpan&ztype=1");
     // Links for 7 samples [10us, 100us) and 3 samples [1ms, 10ms);
@@ -127,11 +127,11 @@ public class TracezPageFormatterTest {
   @Test
   public void linksForFailedRequests_InSummaryTable() {
     OutputStream output = new ByteArrayOutputStream();
-    TracezPageFormatter tracezPageFormatter =
-        TracezPageFormatter.create(runningSpanStore, sampledSpanStore);
+    TracezZPageHandler tracezZPageHandler =
+        TracezZPageHandler.create(runningSpanStore, sampledSpanStore);
     when(runningSpanStore.getSummary()).thenReturn(runningSpanStoreSummary);
     when(sampledSpanStore.getSummary()).thenReturn(sampledSpanStoreSummary);
-    tracezPageFormatter.emitHtml(Collections.emptyMap(), output);
+    tracezZPageHandler.emitHtml(Collections.emptyMap(), output);
     // No sampled links (ztype=1);
     assertThat(output.toString()).doesNotContain("href=\"?zspanname=TestActiveSpan&ztype=2");
     // Links for 7 errors 2 CANCELLED + 5 DEADLINE_EXCEEDED;
diff --git a/contrib/zpages/src/test/java/io/opencensus/zpages/ZPageHandlersTest.java b/contrib/zpages/src/test/java/io/opencensus/zpages/ZPageHandlersTest.java
new file mode 100644
index 00000000..c4b23efc
--- /dev/null
+++ b/contrib/zpages/src/test/java/io/opencensus/zpages/ZPageHandlersTest.java
@@ -0,0 +1,33 @@
+/*
+ * Copyright 2017, OpenCensus Authors
+ *
+ * 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 io.opencensus.zpages;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Unit tests for {@link ZPageHandlers}. */
+@RunWith(JUnit4.class)
+public class ZPageHandlersTest {
+
+  @Test
+  public void implementationOfTracez() {
+    assertThat(ZPageHandlers.getTracezZPageHandler()).isInstanceOf(TracezZPageHandler.class);
+  }
+}
diff --git a/contrib/zpages/src/test/java/io/opencensus/zpages/TracezHttpHandlerTest.java b/contrib/zpages/src/test/java/io/opencensus/zpages/ZPageHttpHandlerTest.java
index 8d76f6fd..fcbeeee2 100644
--- a/contrib/zpages/src/test/java/io/opencensus/zpages/TracezHttpHandlerTest.java
+++ b/contrib/zpages/src/test/java/io/opencensus/zpages/ZPageHttpHandlerTest.java
@@ -24,19 +24,19 @@ import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
 
-/** Unit tests for {@link TracezHttpHandler}. */
+/** Unit tests for {@link ZPageHttpHandler}. */
 @RunWith(JUnit4.class)
-public class TracezHttpHandlerTest {
+public class ZPageHttpHandlerTest {
   @Test
   public void parseUndefinedQuery() throws URISyntaxException {
     URI uri = new URI("http://localhost:8000/tracez");
-    assertThat(TracezHttpHandler.uriQueryToMap(uri)).isEmpty();
+    assertThat(ZPageHttpHandler.uriQueryToMap(uri)).isEmpty();
   }
 
   @Test
   public void parseQuery() throws URISyntaxException {
     URI uri = new URI("http://localhost:8000/tracez?ztype=1&zsubtype&zname=Test");
-    assertThat(TracezHttpHandler.uriQueryToMap(uri))
+    assertThat(ZPageHttpHandler.uriQueryToMap(uri))
         .containsExactly("ztype", "1", "zsubtype", "", "zname", "Test");
   }
 }