Renames to http.route

Author: Adrian Cole

instrumentation/http-tests/src/main/java/brave/http/ITHttpServer.java

@@ -218,7 +218,7 @@ public <Req> void request(HttpAdapter<Req, ?> adapter, Req req, SpanCustomizer c
 
   /**
    * The "/items/{itemId}" endpoint should return the itemId in the response body, which proves
-   * templating worked (including that it ignores query parameters). Note the template format is
+   * templating worked (including that it ignores query parameters). Note the route format is
    * framework specific, ex "/items/:itemId" in vert.x
    */
   @Test
@@ -233,13 +233,13 @@ public <Req> void request(HttpAdapter<Req, ?> adapter, Req req, SpanCustomizer c
       @Override public <Resp> void response(HttpAdapter<?, Resp> adapter, Resp res, Throwable error,
           SpanCustomizer customizer) {
         super.response(adapter, res, error, customizer);
-        String template = adapter.template(res);
+        String template = adapter.route(res);
         if (template != null) customizer.name(template);
       }
     }).build();
     init();
 
-    // Reading the template parameter from the response ensures the test endpoint is correct
+    // Reading the route parameter from the response ensures the test endpoint is correct
     assertThat(get("/items/1?foo").body().string())
         .isEqualTo("1");
     assertThat(get("/items/2?bar").body().string())
@@ -255,7 +255,7 @@ public <Req> void request(HttpAdapter<Req, ?> adapter, Req req, SpanCustomizer c
         .containsEntry("http.path", "/items/2")
         .containsEntry("http.url", url("/items/2?bar"));
 
-    // We don't know the exact format of the http template as it is framework specific
+    // We don't know the exact format of the http route as it is framework specific
     // However, we know that it should match both requests and include the common part of the path
     Set<String> templates = new LinkedHashSet<>(Arrays.asList(span1.name(), span2.name()));
     assertThat(templates).hasSize(1);

instrumentation/http/src/main/java/brave/http/HttpAdapter.java

@@ -38,22 +38,28 @@ public abstract class HttpAdapter<Req, Resp> {
   @Nullable public abstract String requestHeader(Req request, String name);
 
   /**
-   * An expression representing an application endpoint, used to group similar requests together.
+   * An expression such as "/items/:itemId" representing an application endpoint, conventionally
+   * associated with the tag key "http.route".
    *
-   * <p>For example, the template "/products/{key}", would match "/products/1" and "/products/2".
-   * There is no format required for the encoding, as it is sometimes application defined. The
-   * important part is that the value namespace is low cardinality.
+   * <p>The http route groups similar requests together, so results in limited cardinality, often
+   * better choice for a span name vs the http method. However, the route can be absent on redirect
+   * or file-not-found. Also, not all frameworks include support for http route expressions,
+   * and some don't expose templates programmatically for readback.
    *
-   * <p>Conventionally associated with the key "http.template"
+   * <p>For example, the route "/users/{userId}", matches "/users/25f4c31d" and "/users/e3c553be".
+   * If a span name function used the http path instead, it could DOS-style attack vector on your
+   * span name index, as it would grow unbounded vs "/users/{userId}". Even if different frameworks
+   * use different formats, like "/users/[0-9a-f]+" or "/users/:userId", the cardinality is still
+   * fixed with regards to request count.
    *
-   * <p>Eventhough the template is associated with the request, not the response, this is present
+   * <p>Eventhough the route is associated with the request, not the response, this is present
    * on the response object. The reasons is that many server implementations process the request
    * before they can identify the route route.
    */
   // BRAVE5: It isn't possible for a user to easily consume HttpServerAdapter, which is why this
   // method, while generally about the server, is pushed up to the HttpAdapter. The signatures for
   // sampling and parsing could be changed to make it more convenient.
-  @Nullable public String template(Resp response) {
+  @Nullable public String route(Resp response) {
     return null;
   }
 

instrumentation/jaxrs2/src/main/java/brave/jaxrs2/ContainerAdapter.java

@@ -38,8 +38,8 @@ public final class ContainerAdapter
     return request.getHeaderString(name);
   }
 
-  @Override public String template(ContainerResponseContext response) {
-    // There's no portable means to get the template eventhough there is a way in jersey2
+  @Override public String route(ContainerResponseContext response) {
+    // There's no portable means to get the route eventhough there is a way in jersey2
     return null;
   }
 

instrumentation/spring-webmvc/src/main/java/brave/spring/webmvc/TracingHandlerInterceptor.java

@@ -47,7 +47,7 @@ public static HandlerInterceptor create(HttpTracing httpTracing) {
   @Autowired TracingHandlerInterceptor(HttpTracing httpTracing) { // internal
     tracer = httpTracing.tracing().tracer();
     handler = HttpServerHandler.create(httpTracing, new HttpServletAdapter() {
-      @Override public String template(HttpServletResponse response) {
+      @Override public String route(HttpServletResponse response) {
         return response instanceof HttpServletResponseWithTemplate
             ? ((HttpServletResponseWithTemplate) response).template : null;
       }

instrumentation/vertx-web/src/main/java/brave/vertx/web/TracingRoutingContextHandler.java

@@ -24,7 +24,7 @@
  * <p>The hint that we need to re-attach the headers handler on re-route came from looking at
  * {@code TracingHandler} in https://github.com/opentracing-contrib/java-vertx-web
  *
- * <h3>Why use a thread local for the http template when parsing {@linkplain HttpServerResponse}?</h3>
+ * <h3>Why use a thread local for the http route when parsing {@linkplain HttpServerResponse}?</h3>
  * <p>When parsing the response, we use a thread local to make the current route's path visible.
  * This is an alternative to wrapping {@linkplain HttpServerResponse} or declaring a custom type.
  * We don't wrap {@linkplain HttpServerResponse}, because this would lock the instrumentation to the
@@ -130,7 +130,7 @@ static final class Adapter extends HttpServerAdapter<HttpServerRequest, HttpServ
       return request.headers().get(name);
     }
 
-    @Override public String template(HttpServerResponse response) {
+    @Override public String route(HttpServerResponse response) {
       return currentTemplate.get();
     }