Add a simple traceconfigz page. (#590)

* Add a simple traceconfigz page.

* Apply google formatter.

* Fix warning VA_FORMAT_STRING_USES_NEWLINE.

* Add getDescription and polish the HTML.

* Update based on comments.

Author: Bogdan Drutu

api/src/main/java/io/opencensus/trace/Sampler.java

@@ -30,7 +30,7 @@ public abstract class Sampler {
    *     is a root span.
    * @param traceId the {@link TraceId} for the new {@code Span}. This will be identical to that in
    *     the parentContext, unless this is a root span.
-   * @param spanId the span ID for the new {@code Span}.
+   * @param spanId the {@link SpanId} for the new {@code Span}.
    * @param name the name of the new {@code Span}.
    * @param parentLinks the parentLinks associated with the new {@code Span}.
    * @return {@code true} if the {@code Span} is sampled.
@@ -42,4 +42,14 @@ public abstract boolean shouldSample(
       SpanId spanId,
       String name,
       List<Span> parentLinks);
+
+  /**
+   * Returns the description of this {@code Sampler}. This may be displayed on debug pages or in
+   * the logs.
+   *
+   * <p>Example: "ProbabilitySampler{0.000100}"
+   *
+   * @return the description of this {@code Sampler}.
+   */
+  public abstract String getDescription();
 }

api/src/main/java/io/opencensus/trace/samplers/AlwaysSampleSampler.java

@@ -43,6 +43,11 @@ public boolean shouldSample(
     return true;
   }
 
+  @Override
+  public String getDescription() {
+    return toString();
+  }
+
   @Override
   public String toString() {
     return "AlwaysSampleSampler";

api/src/main/java/io/opencensus/trace/samplers/NeverSampleSampler.java

@@ -43,6 +43,11 @@ public boolean shouldSample(
     return false;
   }
 
+  @Override
+  public String getDescription() {
+    return toString();
+  }
+
   @Override
   public String toString() {
     return "NeverSampleSampler";

api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java

@@ -92,4 +92,9 @@ public final boolean shouldSample(
     // code is executed in-line for every Span creation).
     return Math.abs(traceId.getLowerLong()) < getIdUpperBound();
   }
+
+  @Override
+  public final String getDescription() {
+    return String.format("ProbabilitySampler{%.6f}", getProbability());
+  }
 }

contrib/zpages/build.gradle

@@ -8,7 +8,8 @@ apply plugin: 'java'
 }
 
 dependencies {
-    compile project(':opencensus-api')
+    compile project(':opencensus-api'),
+            libraries.guava
 
     signature "org.codehaus.mojo.signature:java18:+@signature"
 }

contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TraceConfigzZPageHandler.java

@@ -0,0 +1,201 @@
+/*
+ * 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.contrib.zpages;
+
+import static com.google.common.base.Strings.isNullOrEmpty;
+
+import com.google.common.base.Charsets;
+import io.opencensus.trace.config.TraceConfig;
+import io.opencensus.trace.config.TraceParams;
+import io.opencensus.trace.samplers.Samplers;
+import java.io.BufferedWriter;
+import java.io.OutputStream;
+import java.io.OutputStreamWriter;
+import java.io.PrintWriter;
+import java.util.Map;
+
+// TODO(bdrutu): Add tests.
+/**
+ * HTML page formatter for tracing config. The page displays information about the current active
+ * tracing configuration and allows users to change it.
+ */
+final class TraceConfigzZPageHandler extends ZPageHandler {
+  private static final String TRACE_CONFIGZ_URL = "/traceconfigz";
+  private final TraceConfig traceConfig;
+
+  private static final String CHANGE = "change";
+  private static final String PERMANENT_CHANGE = "permanently";
+  private static final String RESTORE_DEFAULT_CHANGE = "restore_default";
+  private static final String QUERY_COMPONENT_SAMPLING_PROBABILITY = "samplingprobability";
+  private static final String QUERY_COMPONENT_MAX_NUMBER_OF_ATTRIBUTES = "maxnumberofattributes";
+  private static final String QUERY_COMPONENT_MAX_NUMBER_OF_ANNOTATIONS = "maxnumberofannotations";
+  private static final String QUERY_COMPONENT_MAX_NUMBER_OF_NETWORK_EVENTS =
+      "maxnumberofnetworkevents";
+  private static final String QUERY_COMPONENT_MAX_NUMBER_OF_LINKS = "maxnumberoflinks";
+
+  // TODO(bdrutu): Use post.
+  // TODO(bdrutu): Refactor this to not use a big "printf".
+  private static final String TRACECONFIGZ_FORM_BODY =
+      "<form action=/traceconfigz method=get>%n"
+          // Permanently changes table.
+          + "<table>%n"
+          + "<td colspan=\"3\"><b>Permanently change</b> "
+          + "<input type=\"hidden\" name=\"%s\" value=\"%s\"></td>%n"
+          + "<tr><td>SamplingProbability to</td> "
+          + "<td><input type=text size=10 name=%s value=\"\"></td> <td>(%s)</td>%n"
+          + "<tr><td>MaxNumberOfAttributes to</td> "
+          + "<td><input type=text size=10 name=%s value=\"\"></td> <td>(%d)</td>%n"
+          + "<tr><td>MaxNumberOfAnnotations to</td>"
+          + "<td><input type=text size=10 name=%s value=\"\"></td> <td>(%d)</td>%n"
+          + "<tr><td>MaxNumberOfNetworkEvents to</td> "
+          + "<td><input type=text size=10 name=%s value=\"\"></td> <td>(%d)</td>%n"
+          + "<tr><td>MaxNumberOfLinks to</td>"
+          + "<td><input type=text size=10 name=%s value=\"\"></td> <td>(%d)</td>%n"
+          + "</table>%n"
+          // Submit button.
+          + "<input type=submit value=Submit>%n"
+          + "</form>";
+
+  private static final String RESTORE_DEFAULT_FORM_BODY =
+      "<form action=/traceconfigz method=get>%n"
+          // Restore to default.
+          + "<b>Restore default</b> %n"
+          + "<input type=\"hidden\" name=\"%s\" value=\"%s\"></td>%n"
+          + "</br>%n"
+          // Reset button.
+          + "<input type=submit value=Reset>%n"
+          + "</form>";
+
+  static TraceConfigzZPageHandler create(TraceConfig traceConfig) {
+    return new TraceConfigzZPageHandler(traceConfig);
+  }
+
+  @Override
+  public String getUrlPath() {
+    return TRACE_CONFIGZ_URL;
+  }
+
+  @Override
+  public void emitHtml(Map<String, String> queryMap, OutputStream outputStream) {
+    PrintWriter out =
+        new PrintWriter(new BufferedWriter(new OutputStreamWriter(outputStream, Charsets.UTF_8)));
+    out.write("<!DOCTYPE html>\n");
+    out.write("<html lang=\"en\"><head>\n");
+    out.write("<meta charset=\"utf-8\">\n");
+    out.write("<title>TraceConfigZ</title>\n");
+    out.write("<link rel=\"shortcut icon\" href=\"//www.opencensus.io/favicon.ico\"/>\n");
+    out.write("</head>\n");
+    out.write("<body>\n");
+    try {
+      // Work that can throw exceptions.
+      maybeApplyChanges(queryMap);
+    } finally {
+      // TODO(bdrutu): Maybe display to the page if an exception happened.
+      // Display the page in any case.
+      out.printf(
+          TRACECONFIGZ_FORM_BODY,
+          CHANGE,
+          PERMANENT_CHANGE,
+          QUERY_COMPONENT_SAMPLING_PROBABILITY,
+          "0.0001", // TODO(bdrutu): Get this from the default sampler (if possible).
+          QUERY_COMPONENT_MAX_NUMBER_OF_ATTRIBUTES,
+          TraceParams.DEFAULT.getMaxNumberOfAttributes(),
+          QUERY_COMPONENT_MAX_NUMBER_OF_ANNOTATIONS,
+          TraceParams.DEFAULT.getMaxNumberOfAnnotations(),
+          QUERY_COMPONENT_MAX_NUMBER_OF_NETWORK_EVENTS,
+          TraceParams.DEFAULT.getMaxNumberOfNetworkEvents(),
+          QUERY_COMPONENT_MAX_NUMBER_OF_LINKS,
+          TraceParams.DEFAULT.getMaxNumberOfLinks());
+      out.write("<br>\n");
+      out.printf(RESTORE_DEFAULT_FORM_BODY, CHANGE, RESTORE_DEFAULT_CHANGE);
+      out.write("<br>\n");
+      emitTraceParamsTable(traceConfig.getActiveTraceParams(), out);
+      out.write("</body>\n");
+      out.write("</html>\n");
+      out.close();
+    }
+  }
+
+  // If this is a supported change (currently only permanent changes are supported) apply it.
+  private void maybeApplyChanges(Map<String, String> queryMap) {
+    String changeStr = queryMap.get(CHANGE);
+    if (PERMANENT_CHANGE.equals(changeStr)) {
+      TraceParams.Builder traceParamsBuilder = traceConfig.getActiveTraceParams().toBuilder();
+      String samplingProbabilityStr = queryMap.get(QUERY_COMPONENT_SAMPLING_PROBABILITY);
+      if (!isNullOrEmpty(samplingProbabilityStr)) {
+        double samplingProbability = Double.parseDouble(samplingProbabilityStr);
+        traceParamsBuilder.setSampler(Samplers.probabilitySampler(samplingProbability));
+      }
+      String maxNumberOfAttributesStr = queryMap.get(QUERY_COMPONENT_MAX_NUMBER_OF_ATTRIBUTES);
+      if (!isNullOrEmpty(maxNumberOfAttributesStr)) {
+        int maxNumberOfAttributes = Integer.parseInt(maxNumberOfAttributesStr);
+        traceParamsBuilder.setMaxNumberOfAttributes(maxNumberOfAttributes);
+      }
+      String maxNumberOfAnnotationsStr = queryMap.get(QUERY_COMPONENT_MAX_NUMBER_OF_ANNOTATIONS);
+      if (!isNullOrEmpty(maxNumberOfAnnotationsStr)) {
+        int maxNumberOfAnnotations = Integer.parseInt(maxNumberOfAnnotationsStr);
+        traceParamsBuilder.setMaxNumberOfAnnotations(maxNumberOfAnnotations);
+      }
+      String maxNumberOfNetworkEventsStr =
+          queryMap.get(QUERY_COMPONENT_MAX_NUMBER_OF_NETWORK_EVENTS);
+      if (!isNullOrEmpty(maxNumberOfNetworkEventsStr)) {
+        int maxNumberOfNetworkEvents = Integer.parseInt(maxNumberOfNetworkEventsStr);
+        traceParamsBuilder.setMaxNumberOfNetworkEvents(maxNumberOfNetworkEvents);
+      }
+      String maxNumverOfLinksStr = queryMap.get(QUERY_COMPONENT_MAX_NUMBER_OF_LINKS);
+      if (!isNullOrEmpty(maxNumverOfLinksStr)) {
+        int maxNumberOfLinks = Integer.parseInt(maxNumverOfLinksStr);
+        traceParamsBuilder.setMaxNumberOfLinks(maxNumberOfLinks);
+      }
+      traceConfig.updateActiveTraceParams(traceParamsBuilder.build());
+    } else if (RESTORE_DEFAULT_CHANGE.equals(changeStr)) {
+      traceConfig.updateActiveTraceParams(TraceParams.DEFAULT);
+    }
+  }
+
+  // Prints a table to a PrintWriter that shows existing trace parameters.
+  private static void emitTraceParamsTable(TraceParams params, PrintWriter out) {
+    out.write(
+        "<b>Active tracing parameters:</b><br>\n"
+            + "<table rules=\"all\" frame=\"border\">\n"
+            + "  <tr style=\"background: #eee\">\n"
+            + "    <td><b>Name</b></td>\n"
+            + "    <td><b>Value</b></td>\n"
+            + "  </tr>\n");
+    out.printf(
+        "  <tr>%n    <td>Sampler</td>%n    <td>%s</td>%n  </tr>%n",
+        params.getSampler().getDescription());
+    out.printf(
+        "  <tr>%n    <td>MaxNumberOfAttributes</td>%n    <td>%d</td>%n  </tr>%n",
+        params.getMaxNumberOfAttributes());
+    out.printf(
+        "  <tr>%n    <td>MaxNumberOfAnnotations</td>%n    <td>%d</td>%n  </tr>%n",
+        params.getMaxNumberOfAnnotations());
+    out.printf(
+        "  <tr>%n    <td>MaxNumberOfNetworkEvents</td>%n    <td>%d</td>%n  </tr>%n",
+        params.getMaxNumberOfNetworkEvents());
+    out.printf(
+        "  <tr>%n    <td>MaxNumberOfLinks</td>%n    <td>%d</td>%n  </tr>%n",
+        params.getMaxNumberOfLinks());
+
+    out.write("</table>\n");
+  }
+
+  private TraceConfigzZPageHandler(TraceConfig traceConfig) {
+    this.traceConfig = traceConfig;
+  }
+}

contrib/zpages/src/main/java/io/opencensus/contrib/zpages/TracezZPageHandler.java

@@ -134,7 +134,7 @@ private TracezZPageHandler(
    * @param sampledSpanStore the instance of the {@code SampledSpanStore} to be used.
    * @return a new {@code TracezZPageHandler}.
    */
-  public static TracezZPageHandler create(
+  static TracezZPageHandler create(
       @Nullable RunningSpanStore runningSpanStore, @Nullable SampledSpanStore sampledSpanStore) {
     return new TracezZPageHandler(runningSpanStore, sampledSpanStore);
   }

contrib/zpages/src/main/java/io/opencensus/contrib/zpages/ZPageHandler.java

@@ -40,8 +40,6 @@ public abstract class ZPageHandler {
    */
   public abstract void emitHtml(Map<String, String> queryMap, OutputStream outputStream);
 
-  /**
-   * Package protected constructor to disallow users to extend this class.
-   */
+  /** Package protected constructor to disallow users to extend this class. */
   ZPageHandler() {}
 }

contrib/zpages/src/main/java/io/opencensus/contrib/zpages/ZPageHandlers.java

@@ -65,8 +65,11 @@ public final class ZPageHandlers {
       TracezZPageHandler.create(
           Tracing.getExportComponent().getRunningSpanStore(),
           Tracing.getExportComponent().getSampledSpanStore());
+  private static final ZPageHandler traceConfigzZPageHandler =
+      TraceConfigzZPageHandler.create(Tracing.getTraceConfig());
 
   private static final Object monitor = new Object();
+
   @GuardedBy("monitor")
   private static HttpServer server;
 
@@ -86,13 +89,25 @@ public static ZPageHandler getTracezZPageHandler() {
     return tracezZPageHandler;
   }
 
+  /**
+   * Returns a {@code ZPageHandler} for tracing config. The page displays information about all
+   * active configuration and allow changing the active configuration.
+   *
+   * @return a {@code ZPageHandler} for tracing config.
+   */
+  public static ZPageHandler getTraceConfigzZPageHandler() {
+    return traceConfigzZPageHandler;
+  }
+
   /**
    * 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));
+    server.createContext(
+        traceConfigzZPageHandler.getUrlPath(), new ZPageHttpHandler(traceConfigzZPageHandler));
   }
 
   /**
@@ -124,7 +139,7 @@ public void run() {
                 // Use stderr here since the logger may have been reset by its JVM shutdown hook.
                 logger.fine("*** Shutting down gRPC server (JVM shutting down)");
                 ZPageHandlers.stop();
-                logger.fine("*** server shut down");
+                logger.fine("*** Server shut down");
               }
             });
   }