+at org.springframework.samples.petclinic.owner.OwnerController.initCreationForm(OwnerController.java:60) +... +at org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87) +at org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1040) +at org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:943) +at org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1006) +at org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:898) +at javax.servlet.http.HttpServlet.service(HttpServlet.java:634) +at org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:883) +at javax.servlet.http.HttpServlet.service(HttpServlet.java:741) +... +at org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.java:166) +... +at org.apache.tomcat.util.net.SocketProcessorBase.run(SocketProcessorBase.java:49) +at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128) +at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628) +at org.apache.tomcat.util.threads.TaskThread$WrappingRunnable.run(TaskThread.java:61) +at java.base/java.lang.Thread.run(Thread.java:834) ++ +Everything starts when HTTP request processing reaches the first class from Servlet specification. +In the example above this is `ApplicationFilterChain.doFilter(ServletRequest, ServletResponse)` method. +Let us call this first servlet specific method an "entry point". +This is the main target for `Servlet3Instrumentation` and `Servlet2Instrumentation` instrumenters: + +`public void javax.servlet.FilterChain#doFilter(ServletRequest, ServletResponse)` + +`public void javax.servlet.http.HttpServlet#service(ServletRequest, ServletResponse)`. + +For example, Jetty Servlet container does not have default filter chain and in many cases will have +the second method as instrumentation entry point. +These instrumentations are located in two separate submodules `request-3.0` and `request-2.3`, respectively, +because they and corresponding tests depend on different versions of servlet specification. + +Next, request passes several other methods from Servlet specification, such as + +`protected void javax.servlet.http.HttpServlet#service(HttpServletRequest, HttpServletResponse)` or + +`protected void org.springframework.web.servlet.FrameworkServlet#doGet(HttpServletRequest, HttpServletResponse)`. + +They are the targets for `HttpServletInstrumentation`. +From the observability point of view nothing of interest usually happens inside these methods. +Thus it usually does not make sense to create spans from them, as they would only add useless noise. +For this reason `HttpServletInstrumentation` is disabled by default. +In rare cases when you need it, you can enable it using configuration property `ota.integration.servlet-service.enabled`. + +In exactly the same situation are all other Servlet filters beyond the initial entry point. +Usually unimportant, they may be sometimes of interest during troubleshooting. +They are instrumented by `FilterInstrumentation` which is too disabled by default. +You can enable it with the configuration property `ota.integration.servlet-filter.enabled`. +At last, request processing may reach the specific framework that you application uses. +In this case Spring MVC and `OwnerController.initCreationForm`. + +If all instrumentations are enabled, then a new span will be created for every highlighted frame. +All spans from Servlet API will have `kind=SERVER` and name based on corresponding class ana method names, +such as `ApplicationFilterChain.doFilter` or `FrameworkServlet.doGet`. +Span created by Spring MVC instrumentation will have `kind=INTERNAL` and named `OwnerController.initCreationForm`. + +The state described above has one significant problem. +Observability backends usually aggregate traces based on their root spans. +This means that ALL traces from any application deployed to Servlet container will be grouped together. +Becaue their root spans will all have the same named based on common entry point. +In order to alleviate this problem, instrumentations for specific frameworks, such as Spring MVC here, +_update_ name of the span corresponding to the entry point. +Each framework instrumentation can decide what is the best span name based on framework implementation details. +Of course, still adhering to OpenTelemetry +[semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/semantic_conventions/http.md). \ No newline at end of file diff --git a/instrumentation/servlet/glassfish-testing/src/test/groovy/GlassFishServerTest.groovy b/instrumentation/servlet/glassfish-testing/src/test/groovy/GlassFishServerTest.groovy index 7275beeaea1c..96805043f83e 100644 --- a/instrumentation/servlet/glassfish-testing/src/test/groovy/GlassFishServerTest.groovy +++ b/instrumentation/servlet/glassfish-testing/src/test/groovy/GlassFishServerTest.groovy @@ -36,10 +36,6 @@ import static io.opentelemetry.trace.Span.Kind.SERVER // TODO: Figure out a better way to test with OSGi included. class GlassFishServerTest extends HttpServerTest
javax.servlet.http.HttpServletResponse got method getStatus only
+ * in Servlet specification version 3.0. This means that we cannot set {@link
+ * io.opentelemetry.auto.instrumentation.api.Tags#HTTP_STATUS} attribute on the created span using
+ * just response object.
+ *
+ * This instrumentation intercepts status setting methods from Servlet 2.0 specification and
+ * stores that status into context store. Then {@link Servlet2Advice#stopSpan(ServletRequest,
+ * ServletResponse, SpanWithScope, Throwable)} can get it from context and set required span
+ * attribute.
+ */
@AutoService(Instrumenter.class)
public final class Servlet2ResponseStatusInstrumentation extends Instrumenter.Default {
public Servlet2ResponseStatusInstrumentation() {
@@ -51,16 +68,27 @@ public Map See README.md for more information about different servlet instrumentations.
+ */
@AutoService(Instrumenter.class)
public final class FilterInstrumentation extends Instrumenter.Default {
public FilterInstrumentation() {
diff --git a/instrumentation/servlet/src/main/java/io/opentelemetry/auto/instrumentation/servlet/http/HttpServletInstrumentation.java b/instrumentation/servlet/src/main/java/io/opentelemetry/auto/instrumentation/servlet/http/HttpServletInstrumentation.java
index a2d4c9cf153a..72a95b65fad0 100644
--- a/instrumentation/servlet/src/main/java/io/opentelemetry/auto/instrumentation/servlet/http/HttpServletInstrumentation.java
+++ b/instrumentation/servlet/src/main/java/io/opentelemetry/auto/instrumentation/servlet/http/HttpServletInstrumentation.java
@@ -31,6 +31,7 @@
import io.opentelemetry.auto.instrumentation.api.SpanWithScope;
import io.opentelemetry.auto.tooling.Instrumenter;
import io.opentelemetry.trace.Span;
+import io.opentelemetry.trace.Span.Kind;
import java.lang.reflect.Method;
import java.util.Map;
import net.bytebuddy.asm.Advice;
@@ -38,6 +39,7 @@
import net.bytebuddy.description.type.TypeDescription;
import net.bytebuddy.matcher.ElementMatcher;
+// Please read README.md of this subproject to understand what is this instrumentation.
@AutoService(Instrumenter.class)
public final class HttpServletInstrumentation extends Instrumenter.Default {
public HttpServletInstrumentation() {
@@ -93,7 +95,10 @@ public static SpanWithScope start(@Advice.Origin final Method method) {
}
// Here we use the Method instead of "this.class.name" to distinguish calls to "super".
- final Span span = TRACER.spanBuilder(DECORATE.spanNameForMethod(method)).startSpan();
+ final Span span =
+ TRACER
+ .spanBuilder(DECORATE.spanNameForMethod(method))
+ .startSpan();
DECORATE.afterStart(span);
return new SpanWithScope(span, currentContextWith(span));