better comments

Author: trask

instrumentation/servlet/servlet-3.0/testing/src/main/java/io/opentelemetry/instrumentation/servlet/v3_0/TestServlet3.java

@@ -157,17 +157,19 @@ protected void service(HttpServletRequest req, HttpServletResponse resp) {
                       context.complete();
                     } else if (EXCEPTION.equals(endpoint)) {
                       resp.setStatus(endpoint.getStatus());
+                      // Workaround for a sporadic bug in older Tomcat versions: when the servlet
+                      // throws after writing the async response body, the connection is sometimes
+                      // reset before the response is flushed, which surfaces on the client as
+                      // ClosedSessionException. Other servlet containers (and current Tomcat)
+                      // handle the basic write-then-throw pattern fine, so this workaround is
+                      // scoped to old Tomcat only: set Content-Length so the response is
+                      // self-delimiting, and close the writer to force the flush before the throw.
                       if (req.getClass().getName().contains("catalina") && !testLatestDeps()) {
-                        // Set Content-Length so the response is self-delimiting; combined with
-                        // the writer.close() below, this lets the client read a complete 500
-                        // response on older Tomcat before the post-throw connection reset.
                         resp.setContentLength(endpoint.getBody().length());
                       }
                       PrintWriter writer = resp.getWriter();
                       writer.print(endpoint.getBody());
                       if (req.getClass().getName().contains("catalina") && !testLatestDeps()) {
-                        // Older Tomcat versions may close the connection before sending an async
-                        // response when the servlet throws after writing the response body.
                         writer.close();
                       }
                       throw new IllegalStateException(endpoint.getBody());

instrumentation/servlet/servlet-5.0/testing/src/main/java/io/opentelemetry/javaagent/instrumentation/servlet/v5_0/TestServlet5.java

@@ -155,17 +155,19 @@ protected void service(HttpServletRequest req, HttpServletResponse resp) {
                       context.complete();
                     } else if (EXCEPTION.equals(endpoint)) {
                       resp.setStatus(endpoint.getStatus());
+                      // Workaround for a sporadic bug in older Tomcat versions: when the servlet
+                      // throws after writing the async response body, the connection is sometimes
+                      // reset before the response is flushed, which surfaces on the client as
+                      // ClosedSessionException. Other servlet containers (and current Tomcat)
+                      // handle the basic write-then-throw pattern fine, so this workaround is
+                      // scoped to old Tomcat only: set Content-Length so the response is
+                      // self-delimiting, and close the writer to force the flush before the throw.
                       if (isOldTomcat(req)) {
-                        // Set Content-Length so the response is self-delimiting; combined with
-                        // the writer.close() below, this lets the client read a complete 500
-                        // response on older Tomcat before the post-throw connection reset.
                         resp.setContentLength(endpoint.getBody().length());
                       }
                       PrintWriter writer = resp.getWriter();
                       writer.print(endpoint.getBody());
                       if (isOldTomcat(req)) {
-                        // Older Tomcat versions may close the connection before sending an async
-                        // response when the servlet throws after writing the response body.
                         writer.close();
                       }
                       throw new IllegalStateException(endpoint.getBody());
@@ -242,17 +244,19 @@ protected void service(HttpServletRequest req, HttpServletResponse resp) throws
                 resp.sendError(endpoint.getStatus(), endpoint.getBody());
               } else if (EXCEPTION.equals(endpoint)) {
                 resp.setStatus(endpoint.getStatus());
+                // Workaround for a sporadic bug in older Tomcat versions: when the servlet throws
+                // after writing the async response body, the connection is sometimes reset before
+                // the response is flushed, which surfaces on the client as ClosedSessionException.
+                // Other servlet containers (and current Tomcat) handle the basic write-then-throw
+                // pattern fine, so this workaround is scoped to old Tomcat only: set
+                // Content-Length so the response is self-delimiting, and close the writer to force
+                // the flush before the throw.
                 if (isOldTomcat(req)) {
-                  // Set Content-Length so the response is self-delimiting; combined with the
-                  // writer.close() below, this lets the client read a complete 500 response on
-                  // older Tomcat before the post-throw connection reset.
                   resp.setContentLength(endpoint.getBody().length());
                 }
                 PrintWriter writer = resp.getWriter();
                 writer.print(endpoint.getBody());
                 if (isOldTomcat(req)) {
-                  // Older Tomcat versions may close the connection before sending an async
-                  // response when the servlet throws after writing the response body.
                   writer.close();
                 }
                 throw new IllegalStateException(endpoint.getBody());

instrumentation/tomcat/tomcat-10.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/tomcat/v10_0/AsyncServlet.java

@@ -60,17 +60,19 @@ protected void service(HttpServletRequest req, HttpServletResponse resp) {
                     resp.getWriter().print(endpoint.getBody());
                   } else if (endpoint.equals(EXCEPTION)) {
                     resp.setStatus(endpoint.getStatus());
+                    // Workaround for a sporadic bug in older Tomcat versions: when the servlet
+                    // throws after writing the async response body, the connection is sometimes
+                    // reset before the response is flushed, which surfaces on the client as
+                    // ClosedSessionException. Other servlet containers (and current Tomcat)
+                    // handle the basic write-then-throw pattern fine, so this workaround is
+                    // scoped to old Tomcat only: set Content-Length so the response is
+                    // self-delimiting, and close the writer to force the flush before the throw.
                     if (!testLatestDeps()) {
-                      // Set Content-Length so the response is self-delimiting; combined with
-                      // the writer.close() below, this lets the client read a complete 500
-                      // response on older Tomcat before the post-throw connection reset.
                       resp.setContentLength(endpoint.getBody().length());
                     }
                     PrintWriter writer = resp.getWriter();
                     writer.print(endpoint.getBody());
                     if (!testLatestDeps()) {
-                      // Older Tomcat versions may close the connection before sending an async
-                      // response when the servlet throws after writing the response body.
                       writer.close();
                     }
                     throw new IllegalStateException(endpoint.getBody());

instrumentation/tomcat/tomcat-7.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/tomcat/v7_0/AsyncServlet.java

@@ -59,17 +59,19 @@ protected void service(HttpServletRequest req, HttpServletResponse resp) {
                     resp.getWriter().print(endpoint.getBody());
                   } else if (endpoint.equals(EXCEPTION)) {
                     resp.setStatus(endpoint.getStatus());
+                    // Workaround for a sporadic bug in older Tomcat versions: when the servlet
+                    // throws after writing the async response body, the connection is sometimes
+                    // reset before the response is flushed, which surfaces on the client as
+                    // ClosedSessionException. Other servlet containers (and current Tomcat)
+                    // handle the basic write-then-throw pattern fine, so this workaround is
+                    // scoped to old Tomcat only: set Content-Length so the response is
+                    // self-delimiting, and close the writer to force the flush before the throw.
                     if (!testLatestDeps()) {
-                      // Set Content-Length so the response is self-delimiting; combined with
-                      // the writer.close() below, this lets the client read a complete 500
-                      // response on older Tomcat before the post-throw connection reset.
                       resp.setContentLength(endpoint.getBody().length());
                     }
                     PrintWriter writer = resp.getWriter();
                     writer.print(endpoint.getBody());
                     if (!testLatestDeps()) {
-                      // Older Tomcat versions may close the connection before sending an async
-                      // response when the servlet throws after writing the response body.
                       writer.close();
                     }
                     throw new IllegalStateException(endpoint.getBody());