Instrument Servlet API to add Server-Timing header

README.md

@@ -112,6 +112,12 @@ A simple wrapper for the Jaeger exporter of [opentelemetry-java](https://github.
 | otel.trace.methods                  | OTEL_TRACE_METHODS                 | unset          | Same as adding `@WithSpan` annotation functionality for the target method string. <details><summary>Format</summary>`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`</details>                                                                                                                                                                                                            |
 | otel.trace.annotated.methods.exclude     | OTEL_TRACE_ANNOTATED_METHODS_EXCLUDE    | unset          | Suppress `@WithSpan` instrumentation for specific methods. <details><summary>Format</summary>`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`</details>                                                                                                                                                                                                                                |
 
+### Splunk distribution configuration
+
+| System property                      | Environment variable                 | Default value  | Purpose                                                  |
+| ------------------------------------ | ----------------------------------   | -------------- | -------------------------------------------------------- |
+| splunk.context.server-timing.enabled | SPLUNK_CONTEXT_SERVER_TIMING_ENABLED | false          | Enables adding `Server-Timing` header to HTTP responses. |
+
 ### More options
 For more options see [here](https://github.com/open-telemetry/opentelemetry-java-instrumentation#configuration-parameters-subject-to-change)
 

instrumentation/common/build.gradle

@@ -0,0 +1,12 @@
+plugins {
+    id "java"
+}
+
+dependencies {
+    compileOnly("io.opentelemetry.instrumentation:opentelemetry-instrumentation-api:${versions.opentelemetryJavaagent}")
+    compileOnly("io.opentelemetry:opentelemetry-api:${versions.opentelemetry}")
+
+    // TODO: use versions.opentelemetryJavaagent once distro is updated to 0.15
+    testImplementation("io.opentelemetry.javaagent:opentelemetry-testing-common:0.15.0")
+}
+

instrumentation/common/src/main/java/com/splunk/opentelemetry/servertiming/ServerTimingHeader.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright Splunk Inc.
+ *
+ * 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.splunk.opentelemetry.servertiming;
+
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.context.propagation.TextMapPropagator.Setter;
+import io.opentelemetry.instrumentation.api.config.Config;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Adds {@code Server-Timing} header (and {@code Access-Control-Expose-Headers}) to the HTTP
+ * response. The {@code Server-Timing} header contains the traceId and spanId of the server span.
+ */
+public final class ServerTimingHeader {
+  public static final String SERVER_TIMING = "Server-Timing";
+  public static final String EXPOSE_HEADERS = "Access-Control-Expose-Headers";
+
+  public static boolean shouldEmitServerTimingHeader() {
+    return Config.get().getBooleanProperty("splunk.context.server-timing.enabled", false);
+  }
+
+  public static <RS> void setHeaders(Context context, RS response, Setter<RS> headerSetter) {
+    if (!Span.fromContext(context).getSpanContext().isValid()) {
+      return;
+    }
+
+    headerSetter.set(response, SERVER_TIMING, toHeaderValue(context));
+    headerSetter.set(response, EXPOSE_HEADERS, SERVER_TIMING);
+  }
+
+  private static String toHeaderValue(Context context) {
+    Map<String, String> traceContextHeaders = new HashMap<>();
+    W3CTraceContextPropagator.getInstance().inject(context, traceContextHeaders, Map::put);
+    return String.format("traceparent;desc=\"%s\"", traceContextHeaders.get("traceparent"));
+  }
+
+  private ServerTimingHeader() {}
+}

instrumentation/common/src/test/java/com/splunk/opentelemetry/servertiming/ServerTimingHeaderTest.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright Splunk Inc.
+ *
+ * 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.splunk.opentelemetry.servertiming;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.context.Context;
+import io.opentelemetry.instrumentation.test.utils.TraceUtils;
+import io.opentelemetry.sdk.OpenTelemetrySdk;
+import java.util.HashMap;
+import java.util.Map;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class ServerTimingHeaderTest {
+  @BeforeAll
+  static void setUpOpenTelemetry() {
+    OpenTelemetrySdk.builder().buildAndRegisterGlobal();
+  }
+
+  @Test
+  void shouldNotSetAnyHeadersWithoutValidCurrentSpan() {
+    // given
+    var headers = new HashMap<String, String>();
+
+    // when
+    ServerTimingHeader.setHeaders(Context.current(), headers, Map::put);
+
+    // then
+    assertTrue(headers.isEmpty());
+  }
+
+  @Test
+  void shouldSetHeaders() {
+    // given
+    var headers = new HashMap<String, String>();
+
+    // when
+    var spanContext =
+        TraceUtils.runUnderTrace(
+            "server",
+            () -> {
+              ServerTimingHeader.setHeaders(Context.current(), headers, Map::put);
+              return Span.current().getSpanContext();
+            });
+
+    // then
+    assertEquals(2, headers.size());
+
+    var serverTimingHeaderValue =
+        "traceparent;desc=\"00-"
+            + spanContext.getTraceIdAsHexString()
+            + "-"
+            + spanContext.getSpanIdAsHexString()
+            + "-01\"";
+    assertEquals(serverTimingHeaderValue, headers.get(ServerTimingHeader.SERVER_TIMING));
+    assertEquals(ServerTimingHeader.SERVER_TIMING, headers.get(ServerTimingHeader.EXPOSE_HEADERS));
+  }
+}

instrumentation/servlet-3-testing/build.gradle

@@ -0,0 +1,21 @@
+apply from: "$rootDir/gradle/instrumentation.gradle"
+
+dependencies {
+    testInstrumentation group: 'io.opentelemetry.javaagent.instrumentation', name: 'opentelemetry-javaagent-servlet-common', version: versions.opentelemetryJavaagent
+    testInstrumentation group: 'io.opentelemetry.javaagent.instrumentation', name: 'opentelemetry-javaagent-servlet-2.2', version: versions.opentelemetryJavaagent
+    testInstrumentation group: 'io.opentelemetry.javaagent.instrumentation', name: 'opentelemetry-javaagent-servlet-3.0', version: versions.opentelemetryJavaagent
+    testInstrumentation project(':instrumentation:servlet')
+
+    testImplementation project(':instrumentation:common')
+    testImplementation("io.opentelemetry.javaagent:opentelemetry-testing-common:0.15.0-SNAPSHOT") {
+        exclude group: 'org.eclipse.jetty', module: 'jetty-server'
+    }
+
+    testImplementation group: 'javax.servlet', name: 'javax.servlet-api', version: '3.0.1'
+    testImplementation group: 'org.eclipse.jetty', name: 'jetty-server', version: '8.0.0.v20110901'
+    testImplementation group: 'org.eclipse.jetty', name: 'jetty-servlet', version: '8.0.0.v20110901'
+}
+
+tasks.withType(Test) {
+    jvmArgs '-Dsplunk.context.server-timing.enabled=true'
+}

instrumentation/servlet-3-testing/src/test/java/com/splunk/opentelemetry/servlet/Servlet3InstrumentationTest.java

@@ -0,0 +1,176 @@
+/*
+ * Copyright Splunk Inc.
+ *
+ * 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.splunk.opentelemetry.servlet;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.splunk.opentelemetry.servertiming.ServerTimingHeader;
+import io.opentelemetry.instrumentation.test.AgentTestRunner;
+import io.opentelemetry.instrumentation.test.utils.OkHttpUtils;
+import io.opentelemetry.instrumentation.test.utils.PortUtils;
+import java.io.IOException;
+import java.io.Writer;
+import java.util.EnumSet;
+import java.util.concurrent.TimeoutException;
+import javax.servlet.DispatcherType;
+import javax.servlet.Filter;
+import javax.servlet.FilterChain;
+import javax.servlet.FilterConfig;
+import javax.servlet.ServletRequest;
+import javax.servlet.ServletResponse;
+import javax.servlet.http.HttpServlet;
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import okhttp3.HttpUrl;
+import okhttp3.OkHttpClient;
+import okhttp3.Request;
+import okhttp3.Response;
+import org.eclipse.jetty.server.Server;
+import org.eclipse.jetty.servlet.DefaultServlet;
+import org.eclipse.jetty.servlet.ServletContextHandler;
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.AfterEach;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.Test;
+
+class Servlet3InstrumentationTest extends AgentTestRunner {
+
+  private static final OkHttpClient httpClient = OkHttpUtils.client();
+
+  private static int port;
+  private static Server server;
+
+  @BeforeAll
+  static void startServer() throws Exception {
+    port = PortUtils.randomOpenPort();
+    server = new Server(port);
+    for (var connector : server.getConnectors()) {
+      connector.setHost("localhost");
+    }
+
+    var servletContext = new ServletContextHandler(null, null);
+    servletContext.addServlet(DefaultServlet.class, "/");
+    servletContext.addServlet(TestServlet.class, "/servlet");
+    servletContext.addFilter(TestFilter.class, "/filter", EnumSet.of(DispatcherType.REQUEST));
+    server.setHandler(servletContext);
+
+    server.start();
+  }
+
+  @AfterAll
+  static void stopServer() throws Exception {
+    server.stop();
+    server.destroy();
+  }
+
+  @AfterEach
+  void clearTraces() {
+    TEST_WRITER.clear();
+  }
+
+  @Test
+  void shouldHttpServletAddServerTimingHeader() throws Exception {
+    // given
+    var request =
+        new Request.Builder()
+            .url(HttpUrl.get("http://localhost:" + port + "/servlet"))
+            .get()
+            .build();
+
+    // when
+    var response = httpClient.newCall(request).execute();
+
+    // then
+    assertEquals(200, response.code());
+    assertEquals("result", response.body().string());
+
+    var serverTimingHeader = response.header(ServerTimingHeader.SERVER_TIMING);
+    assertHeaders(response, serverTimingHeader);
+    assertServerTimingHeaderContainsTraceId(serverTimingHeader);
+  }
+
+  @Test
+  void shouldHttpFilterAddServerTimingHeader() throws Exception {
+    // given
+    var request =
+        new Request.Builder()
+            .url(HttpUrl.get("http://localhost:" + port + "/filter"))
+            .get()
+            .build();
+
+    // when
+    var response = httpClient.newCall(request).execute();
+
+    // then
+    assertEquals(200, response.code());
+    assertEquals("result", response.body().string());
+
+    var serverTimingHeader = response.header(ServerTimingHeader.SERVER_TIMING);
+    assertHeaders(response, serverTimingHeader);
+    assertServerTimingHeaderContainsTraceId(serverTimingHeader);
+  }
+
+  private static void assertHeaders(Response response, String serverTimingHeader) {
+    assertNotNull(serverTimingHeader);
+    assertEquals(
+        ServerTimingHeader.SERVER_TIMING, response.header(ServerTimingHeader.EXPOSE_HEADERS));
+  }
+
+  private static void assertServerTimingHeaderContainsTraceId(String serverTimingHeader)
+      throws InterruptedException, TimeoutException {
+    TEST_WRITER.waitForTraces(1);
+
+    var traces = TEST_WRITER.getTraces();
+    assertEquals(1, traces.size());
+
+    var spans = traces.get(0);
+    assertEquals(1, spans.size());
+
+    var serverSpan = spans.get(0);
+    assertTrue(serverTimingHeader.contains(serverSpan.getTraceId()));
+  }
+
+  public static class TestServlet extends HttpServlet {
+    protected void doGet(HttpServletRequest request, HttpServletResponse response)
+        throws IOException {
+      try (Writer writer = response.getWriter()) {
+        writer.write("result");
+        response.setStatus(200);
+      }
+    }
+  }
+
+  public static class TestFilter implements Filter {
+    @Override
+    public void init(FilterConfig filterConfig) {}
+
+    @Override
+    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
+        throws IOException {
+      var httpResponse = (HttpServletResponse) response;
+      try (Writer writer = httpResponse.getWriter()) {
+        writer.write("result");
+        httpResponse.setStatus(200);
+      }
+    }
+
+    @Override
+    public void destroy() {}
+  }
+}

instrumentation/servlet/build.gradle

@@ -0,0 +1,28 @@
+apply from: "$rootDir/gradle/instrumentation.gradle"
+
+dependencies {
+    compileOnly group: 'javax.servlet', name: 'servlet-api', version: '2.2'
+
+    implementation project(':instrumentation:common')
+
+    testInstrumentation group: 'io.opentelemetry.javaagent.instrumentation', name: 'opentelemetry-javaagent-servlet-common', version: versions.opentelemetryJavaagent
+    testInstrumentation group: 'io.opentelemetry.javaagent.instrumentation', name: 'opentelemetry-javaagent-servlet-2.2', version: versions.opentelemetryJavaagent
+    testInstrumentation group: 'io.opentelemetry.javaagent.instrumentation', name: 'opentelemetry-javaagent-servlet-3.0', version: versions.opentelemetryJavaagent
+
+    // TODO: use versions.opentelemetryJavaagent once distro is updated to 0.15
+    testImplementation("io.opentelemetry.javaagent:opentelemetry-testing-common:0.15.0") {
+        exclude group: 'org.eclipse.jetty', module: 'jetty-server'
+    }
+
+    testImplementation group: 'javax.servlet', name: 'servlet-api', version: '2.2'
+    testImplementation group: 'org.eclipse.jetty', name: 'jetty-servlet', version: '7.0.0.v20091005'
+    testImplementation(group: 'org.eclipse.jetty', name: 'jetty-server')  {
+        version {
+            strictly '7.0.0.v20091005'
+        }
+    }
+}
+
+tasks.withType(Test) {
+    jvmArgs '-Dsplunk.context.server-timing.enabled=true'
+}