Catch exception variable naming (open-telemetry#17220)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: trask

.github/agents/knowledge/general-rules.md

@@ -17,6 +17,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Style | Style guide | Always | — |
 | Style | Uppercase field names should reflect semantic constants or immutable value constants such as `Duration` timeouts/intervals, not simply `static final` | Always | — |
 | Naming | Getter naming (`get` / `is`) | Always | — |
+| Style | Prefer `e` for used exceptions, prefer `f` for used exceptions in nested catch clauses when an outer catch already uses `e`, allow `error` for specific `*Error` catch types, prefer `t` for used `Throwable` values, prefer `ignored` for intentionally unused catch parameters, and use `ignore` for nested intentionally unused catch parameters when `ignored` would shadow an outer catch variable | Catch clauses, `Throwable` params | — |
 | Naming | Module/package naming | New or renamed modules/packages | `module-naming.md` |
 | Javaagent | Advice patterns | `@Advice` classes | `javaagent-advice-patterns.md` |
 | Javaagent | Module structure patterns | `InstrumentationModule`, `TypeInstrumentation` | `javaagent-module-patterns.md` |
@@ -56,6 +57,21 @@ Flag real defects, including:
 
 Only flag substantive problems, not stylistic preference.
 
+## [Javaagent] Best-Effort Suppressed Failures
+
+When javaagent runtime code intentionally suppresses a `Throwable` to avoid breaking the
+application, do not silently swallow it.
+
+- Prefer `ExceptionLogger.logSuppressedError(...)` for suppressed failures in javaagent code.
+  It logs at `FINE` and matches the agent's default ByteBuddy advice suppression path in
+  `ExceptionHandlers.defaultExceptionHandler()`.
+- Use this for best-effort hooks such as response customizers, bootstrap fallbacks, or other
+  optional extension points where failure must not change application behavior.
+- Do not introduce ad-hoc local loggers for one-off suppressed javaagent failures when
+  `ExceptionLogger` is available from bootstrap.
+- Keep the message action-oriented and specific (for example, "Failed to customize Netty 4.1
+  HTTP server response").
+
 ## [Style] Style Guide
 
 Read and apply `docs/contributing/style-guide.md`.
@@ -87,6 +103,28 @@ Do not flag the following patterns (common false positives):
 
 Public API getters should use `get*` (or `is*` for booleans).
 
+## [Style] Catch Exception Variable Naming
+
+Prefer `e` as the exception variable name in catch clauses when the exception is
+used.
+
+For nested catch clauses, when an outer catch already uses `e`, prefer `f` as the
+inner exception variable name when the exception is used.
+
+`error` is also acceptable when the caught type is a specific `*Error` subtype.
+
+Prefer `t` for used `Throwable` values, including `catch (Throwable t)` and
+`Throwable` callback parameters.
+
+If a catch parameter is intentionally unused, prefer `ignored` over `ignore`.
+
+For nested catch clauses, if `ignored` would shadow an outer catch variable,
+prefer `ignore` for the inner intentionally unused catch parameter.
+
+Both `ignored` and `ignore` are recognized by IntelliJ's `CatchMayIgnoreException`
+inspection as intentional unused-catch names. In test sources, IntelliJ also
+recognizes `expected` and `ok`.
+
 ## [Style] Prefer Instance Creation Over Singletons
 
 Stateless implementations of telemetry interfaces — `TextMapGetter`, `TextMapSetter`,

instrumentation/grails-3.0/javaagent/src/test/java/test/GrailsTest.java

@@ -86,7 +86,7 @@ private static String getContextPathKey() {
       try {
         ServerProperties.class.getDeclaredMethod("getServlet");
         return "server.servlet.contextPath";
-      } catch (NoSuchMethodException ignore) {
+      } catch (NoSuchMethodException ignored) {
         return "server.context-path";
       }
     }

instrumentation/grpc-1.6/library/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/BodySizeUtil.java

@@ -18,15 +18,15 @@ final class BodySizeUtil {
   private static Class<?> getMessageLiteClass() {
     try {
       return Class.forName("com.google.protobuf.MessageLite");
-    } catch (Exception ignore) {
+    } catch (Exception ignored) {
       return null;
     }
   }
 
   private static Method getSerializedSizeMethod(Class<?> clazz) {
     try {
       return clazz.getMethod("getSerializedSize");
-    } catch (NoSuchMethodException ignore) {
+    } catch (NoSuchMethodException ignored) {
       return null;
     }
   }
@@ -40,7 +40,7 @@ static <T> Long getBodySize(T message) {
     }
     try {
       return ((Integer) serializedSizeMethod.invoke(message)).longValue();
-    } catch (Throwable ignore) {
+    } catch (Throwable ignored) {
       return null;
     }
   }

instrumentation/grpc-1.6/testing/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/AbstractGrpcStreamingTest.java

@@ -500,7 +500,7 @@ private static void usePlainText(ManagedChannelBuilder<?> channelBuilder) throws
           .getClass()
           .getMethod("usePlaintext", boolean.class)
           .invoke(channelBuilder, true);
-    } catch (NoSuchMethodException unused) {
+    } catch (NoSuchMethodException ignored) {
       channelBuilder.getClass().getMethod("usePlaintext").invoke(channelBuilder);
     }
   }

instrumentation/grpc-1.6/testing/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/AbstractGrpcTest.java

@@ -1703,7 +1703,7 @@ private static void usePlainText(ManagedChannelBuilder<?> channelBuilder) throws
           .getClass()
           .getMethod("usePlaintext", boolean.class)
           .invoke(channelBuilder, true);
-    } catch (NoSuchMethodException unused) {
+    } catch (NoSuchMethodException ignored) {
       channelBuilder.getClass().getMethod("usePlaintext").invoke(channelBuilder);
     }
   }

instrumentation/jaxws/jaxws-metro-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/metro/SoapFaultBuilderInstrumentation.java

@@ -45,7 +45,7 @@ public static void onExit(@Advice.Argument(2) Throwable throwable) {
       // if fiber is not attached current() throws IllegalStateException
       try {
         request = Fiber.current().getPacket();
-      } catch (IllegalStateException ignore) {
+      } catch (IllegalStateException ignored) {
         // fiber not available
       }
       if (request != null) {

instrumentation/jaxws/jaxws-metro-2.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/metro/TracingTube.java

@@ -54,7 +54,7 @@ public NextAction processException(Throwable throwable) {
     // if fiber is not attached current() throws IllegalStateException
     try {
       request = Fiber.current().getPacket();
-    } catch (IllegalStateException ignore) {
+    } catch (IllegalStateException ignored) {
       // fiber not available
     }
     if (request != null) {

instrumentation/jdbc/library/src/main/java/io/opentelemetry/instrumentation/jdbc/internal/JdbcUtils.java

@@ -109,7 +109,7 @@ public static DbInfo computeDbInfo(@Nullable Connection connection) {
       if (url != null) {
         try {
           return JdbcConnectionUrlParser.parse(url, connection.getClientInfo());
-        } catch (Throwable ex) {
+        } catch (Throwable ignored) {
           // getClientInfo is likely not allowed.
           return JdbcConnectionUrlParser.parse(url, null);
         }

instrumentation/jdbc/testing/src/main/java/io/opentelemetry/instrumentation/jdbc/testing/AbstractJdbcInstrumentationTest.java

@@ -140,8 +140,8 @@ static void tearDown() {
                           if (dataSource instanceof Closeable) {
                             try {
                               ((Closeable) dataSource).close();
-                            } catch (IOException ignore) {
-                              // ignore
+                            } catch (IOException ignored) {
+                              // ignore exceptions during close
                             }
                           }
                         }));

instrumentation/jetty/jetty-8.0/javaagent/src/test/java/io/opentelemetry/javaagent/instrumentation/jetty/v8_0/QueuedThreadPoolTest.java

@@ -5,7 +5,7 @@
 
 package io.opentelemetry.javaagent.instrumentation.jetty.v8_0;
 
-import static org.junit.jupiter.api.Assumptions.assumeTrue;
+import static org.junit.jupiter.api.Assumptions.abort;
 
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.instrumentation.testing.junit.AgentInstrumentationExtension;
@@ -25,29 +25,26 @@ void dispatchPropagates() throws Exception {
     QueuedThreadPool pool = new QueuedThreadPool();
     // run test only if QueuedThreadPool has dispatch method
     // dispatch method was removed in jetty 9.1
-    Method dispatch = null;
+    Method dispatch;
     try {
       dispatch = QueuedThreadPool.class.getMethod("dispatch", Runnable.class);
-    } catch (NoSuchMethodException ignore) {
-      // ignore
+    } catch (NoSuchMethodException ignored) {
+      abort("Jetty 9.1+ removed dispatch(Runnable)");
+      return;
     }
-    assumeTrue(dispatch != null);
     pool.start();
 
-    Method finalDispatch = dispatch;
     testing.runWithSpan(
         "parent",
         () -> {
           // this child will have a span
           JavaAsyncChild child1 = new JavaAsyncChild();
           // this child won't
           JavaAsyncChild child2 = new JavaAsyncChild(false, false);
-          if (finalDispatch != null) {
-            finalDispatch.invoke(pool, child1);
-            finalDispatch.invoke(pool, child2);
-            child1.waitForCompletion();
-            child2.waitForCompletion();
-          }
+          dispatch.invoke(pool, child1);
+          dispatch.invoke(pool, child2);
+          child1.waitForCompletion();
+          child2.waitForCompletion();
         });
 
     testing.waitAndAssertTraces(
@@ -67,23 +64,20 @@ void dispatchPropagatesLambda() throws Exception {
     QueuedThreadPool pool = new QueuedThreadPool();
     // run test only if QueuedThreadPool has dispatch method
     // dispatch method was removed in jetty 9.1
-    Method dispatch = null;
+    Method dispatch;
     try {
       dispatch = QueuedThreadPool.class.getMethod("dispatch", Runnable.class);
-    } catch (NoSuchMethodException ignore) {
-      // ignore
+    } catch (NoSuchMethodException ignored) {
+      abort("Jetty 9.1+ removed dispatch(Runnable)");
+      return;
     }
-    assumeTrue(dispatch != null);
     pool.start();
 
     JavaAsyncChild child = new JavaAsyncChild(true, true);
-    Method finalDispatch = dispatch;
     testing.runWithSpan(
         "parent",
         () -> {
-          if (finalDispatch != null) {
-            finalDispatch.invoke(pool, JavaLambdaMaker.lambda(child));
-          }
+          dispatch.invoke(pool, JavaLambdaMaker.lambda(child));
         });
 
     // We block in child to make sure spans close in predictable order