Add explanatory comments to @SuppressWarnings for ErrorProne 2.44.0

agent/agent-bootstrap/src/main/java/com/microsoft/applicationinsights/agent/bootstrap/BytecodeUtil.java

@@ -18,7 +18,7 @@
 import javax.annotation.Nullable;
 
 // supporting all properties of event, metric, remote dependency and page view telemetry
-@SuppressWarnings("TooManyParameters")
+@SuppressWarnings("TooManyParameters") // parameter count justified by method complexity
 public class BytecodeUtil {
 
   private static BytecodeUtilDelegate delegate;
@@ -324,7 +324,7 @@ public static void onEnter() {
     startNanosHolder.set(System.nanoTime());
   }
 
-  @SuppressWarnings("SystemOut")
+  @SuppressWarnings("SystemOut") // legitimate use of System.out for logging/output
   public static void onExit() {
     Long startNanos = startNanosHolder.get();
     if (startNanos == null) {

agent/agent-gc-monitor/gc-monitor-api/src/main/java/com/microsoft/gcmonitor/MemoryManagers.java

@@ -27,7 +27,8 @@ public enum MemoryManagers {
 
   ZGC(GarbageCollectors.Zgc.class);
 
-  @SuppressWarnings("ImmutableEnumChecker")
+  @SuppressWarnings(
+      "ImmutableEnumChecker") // mutable enum state is intentional and properly synchronized
   private final Class<? extends GarbageCollector>[] managers;
 
   public static MemoryManagers of(MemoryManagement manager) {

agent/agent-gc-monitor/gc-monitor-api/src/main/java/com/microsoft/gcmonitor/memorypools/MemoryPools.java

@@ -300,7 +300,10 @@ public Shenandoah(Set<GarbageCollector> managers) {
     }
   }
 
-  @SuppressWarnings({"checkstyle:AbbreviationAsWordInName", "MemberName"})
+  @SuppressWarnings({
+    "checkstyle:AbbreviationAsWordInName",
+    "MemberName"
+  }) // CGroup is the standard abbreviation for Control Group
   public static class ZHeap extends MemoryPool {
     public static final String POOL_NAME = "ZHeap";
 

agent/agent-gc-monitor/gc-monitor-core/src/main/java/com/microsoft/gcmonitor/collectors/GcCollectionSample.java

@@ -63,7 +63,7 @@ public GcCollectionSample(
 
   private static Map<MemoryPool, MemoryUsage> groupMemoryUsageByPoolName(
       Object map, MemoryManagement memoryManagement) {
-    @SuppressWarnings("unchecked")
+    @SuppressWarnings("unchecked") // safe unchecked cast - type verified by runtime context
     Map<List<String>, CompositeData> byName = (Map<List<String>, CompositeData>) map;
     Map<MemoryPool, MemoryUsage> byIdentifier = new HashMap<>();
     try {

agent/agent-gc-monitor/gc-monitor-tests/src/test/java/com/microsoft/gcmonitortests/GcEventGenerator.java

@@ -25,7 +25,7 @@ public static void main(String[] args) throws InterruptedException {
     new GcEventGenerator().run();
   }
 
-  @SuppressWarnings("SystemOut")
+  @SuppressWarnings("SystemOut") // legitimate use of System.out for logging/output
   private void run() throws InterruptedException {
     System.out.println("Hit return to start");
 

agent/agent-gc-monitor/gc-monitor-tests/src/test/java/com/microsoft/gcmonitortests/GcProcessRunner.java

@@ -25,7 +25,11 @@
 import javax.management.remote.JMXServiceURL;
 
 // TODO (trask) revisit Java8ApiChecker suppression
-@SuppressWarnings({"Java8ApiChecker", "SystemOut", "CatchAndPrintStackTrace"})
+@SuppressWarnings({
+  "Java8ApiChecker",
+  "SystemOut",
+  "CatchAndPrintStackTrace"
+}) // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 public class GcProcessRunner {
   private InputStream errorStream;
   private InputStream stdOut;

agent/agent-gc-monitor/gc-monitor-tests/src/test/java/com/microsoft/gcmonitortests/VariousCollectorsTest.java

@@ -100,7 +100,7 @@ private static boolean isPresent(
     return events.stream().anyMatch(predicate);
   }
 
-  @SuppressWarnings({"SystemOut", "unused"})
+  @SuppressWarnings({"SystemOut", "unused"}) // legitimate use of System.out for logging/output
   private static void print(List<GcCollectionEvent> events) {
     System.out.println("Obtained: " + events.size());
     events.forEach(

agent/agent-profiler/agent-alerting/src/main/java/com/microsoft/applicationinsights/alerting/analysis/pipelines/AlertPipelineMXBean.java

@@ -4,7 +4,10 @@
 package com.microsoft.applicationinsights.alerting.analysis.pipelines;
 
 // This class name must end in MXBean (case sensitive)
-@SuppressWarnings({"checkstyle:AbbreviationAsWordInName", "IdentifierName"})
+@SuppressWarnings({
+  "checkstyle:AbbreviationAsWordInName",
+  "IdentifierName"
+}) // CGroup is the standard abbreviation for Control Group
 public interface AlertPipelineMXBean {
 
   // Attributes

agent/agent-profiler/agent-diagnostics-jfr/src/main/java/com/microsoft/applicationinsights/diagnostics/jfr/AlertBreachJfrEvent.java

@@ -15,7 +15,9 @@
 import jdk.jfr.Name;
 import jdk.jfr.StackTrace;
 
-@SuppressWarnings({"Java8ApiChecker"})
+@SuppressWarnings({
+  "Java8ApiChecker"
+}) // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 @Name("com.microsoft.applicationinsights.diagnostics.jfr.AlertBreach")
 @Label("AlertBreach")
 @Category("Diagnostic")

agent/agent-profiler/agent-diagnostics-jfr/src/main/java/com/microsoft/applicationinsights/diagnostics/jfr/CGroupData.java

@@ -16,7 +16,10 @@
 import jdk.jfr.Period;
 import jdk.jfr.StackTrace;
 
-@SuppressWarnings({"Java8ApiChecker", "AbbreviationAsWordInName"})
+@SuppressWarnings({
+  "Java8ApiChecker",
+  "AbbreviationAsWordInName"
+}) // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 @Name("com.microsoft.applicationinsights.diagnostics.jfr.CGroupData")
 @Label("CGroupData")
 @Category("Diagnostic")

agent/agent-profiler/agent-diagnostics-jfr/src/main/java/com/microsoft/applicationinsights/diagnostics/jfr/MachineStats.java

@@ -16,7 +16,7 @@
 import jdk.jfr.Period;
 import jdk.jfr.StackTrace;
 
-@SuppressWarnings("Java8ApiChecker")
+@SuppressWarnings("Java8ApiChecker") // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 @Name("com.microsoft.applicationinsights.diagnostics.jfr.MachineStats")
 @Label("MachineStats")
 @Category("Diagnostic")

agent/agent-profiler/agent-diagnostics-jfr/src/main/java/com/microsoft/applicationinsights/diagnostics/jfr/Telemetry.java

@@ -18,7 +18,9 @@
 import jdk.jfr.Period;
 import jdk.jfr.StackTrace;
 
-@SuppressWarnings({"Java8ApiChecker"})
+@SuppressWarnings({
+  "Java8ApiChecker"
+}) // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 @Name("com.microsoft.applicationinsights.diagnostics.jfr.Telemetry")
 @Label("Telemetry")
 @Category("Diagnostic")
@@ -46,7 +48,7 @@ public String getTelemetry() {
     return telemetry;
   }
 
-  @SuppressWarnings("unchecked")
+  @SuppressWarnings("unchecked") // safe unchecked cast - type verified by runtime context
   public Telemetry setTelemetry(Object telemetry) {
     if (telemetry instanceof List) {
       StringJoiner joiner = new StringJoiner(",");

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/SystemStatsReader.java

@@ -27,7 +27,9 @@ public class SystemStatsReader implements Closeable {
 
   private final KernelMonitorDeviceDriver driver;
 
-  @SuppressWarnings("checkstyle:MemberName")
+  @SuppressWarnings(
+      "checkstyle:MemberName") // naming convention intentionally differs from checkstyle for
+  // consistency
   private final CGroupUsageDataReader cGroupUsageDataReader;
 
   private final ProcessCpuStats processCpuStats;
@@ -39,7 +41,10 @@ public class SystemStatsReader implements Closeable {
 
   public SystemStatsReader(
       KernelMonitorDeviceDriver driver,
-      @SuppressWarnings("checkstyle:ParameterName") CGroupUsageDataReader cGroupUsageDataReader,
+      @SuppressWarnings("checkstyle:ParameterName")
+          CGroupUsageDataReader
+              cGroupUsageDataReader, // parameter naming intentionally differs from checkstyle for
+      // consistency
       ProcessCpuStats processCpuStats,
       ProcessIoStats ioStats,
       MemoryInfoReader memoryInfoReader) {

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/calibration/ContextSwitchingRunner.java

@@ -27,14 +27,15 @@ public static void main(String[] args) {
     new ContextSwitchingRunner().runThreads(1000);
   }
 
-  @SuppressWarnings("ThreadJoinLoop")
+  @SuppressWarnings(
+      "ThreadJoinLoop") // thread join in loop is safe and necessary for proper synchronization
   private void runThreads(int threadCount) {
     Thread[] threads = new Thread[threadCount];
 
     for (int i = 0; i < threads.length; i++) {
       threads[i] =
           new Thread() {
-            @SuppressWarnings("unused")
+            @SuppressWarnings("unused") // value not used but required by API signature or framework
             private int value = 0;
 
             @Override

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/jvm/ProcessData.java

@@ -175,7 +175,8 @@ public int hashCode() {
   }
 
   @Override
-  @SuppressWarnings("EqualsGetClass")
+  @SuppressWarnings(
+      "EqualsGetClass") // using getClass() in equals is intentional for this type hierarchy
   public boolean equals(Object obj) {
     if (this == obj) {
       return true;

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/kernel/CGroupDataReader.java

@@ -6,7 +6,8 @@
 import com.microsoft.applicationinsights.diagnostics.collection.libos.OperatingSystemInteractionException;
 
 /** Reads CGroup data from the host OS */
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public interface CGroupDataReader {
 
   long getKmemLimit() throws OperatingSystemInteractionException;

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/kernel/CGroupUsageDataReader.java

@@ -8,7 +8,8 @@
 import java.util.List;
 import javax.annotation.Nullable;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public interface CGroupUsageDataReader extends TwoStepUpdatable, Closeable {
   @Nullable
   List<Double> getTelemetry();

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/LinuxKernelStats.java

@@ -128,7 +128,7 @@ public void update() throws OperatingSystemInteractionException {
     }
   }
 
-  @SuppressWarnings({"AvoidObjectArrays"})
+  @SuppressWarnings({"AvoidObjectArrays"}) // object array required by API or framework
   public static int lineIndexFor(String[] procStatContents, String lineContents) {
     int index = 0;
     while (index < procStatContents.length && !procStatContents[index].contains(lineContents)) {

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/LinuxProcessDumper.java

@@ -32,7 +32,10 @@ public LinuxProcessDumper(boolean isDaemon, int thisPid) {
   }
 
   @Override
-  @SuppressWarnings({"unchecked", "rawtypes"})
+  @SuppressWarnings({
+    "unchecked",
+    "rawtypes"
+  }) // safe unchecked cast - type verified by runtime context
   public Iterable<Process> all(boolean includeSelf) {
     if (includeSelf || !isDaemon) {
       return (Iterable) usage.values();

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/cgroups/CGroupCpuSystemReader.java

@@ -3,7 +3,8 @@
 
 package com.microsoft.applicationinsights.diagnostics.collection.libos.os.linux.cgroups;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public class CGroupCpuSystemReader extends CGroupValueReader {
   // total system CPU time (in nanoseconds) consumed by all tasks in this cgroup
   public CGroupCpuSystemReader() {

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/cgroups/CGroupCpuUsageReader.java

@@ -3,7 +3,8 @@
 
 package com.microsoft.applicationinsights.diagnostics.collection.libos.os.linux.cgroups;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public class CGroupCpuUsageReader extends CGroupValueReader {
   // total CPU usage (in nanoseconds) consumed by all tasks in this cgroup
   public CGroupCpuUsageReader() {

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/cgroups/CGroupCpuUserReader.java

@@ -3,7 +3,8 @@
 
 package com.microsoft.applicationinsights.diagnostics.collection.libos.os.linux.cgroups;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public class CGroupCpuUserReader extends CGroupValueReader {
   // total user CPU time (in nanoseconds) consumed by all tasks in this cgroup
   public CGroupCpuUserReader() {

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/cgroups/CGroupStatReader.java

@@ -7,7 +7,8 @@
 import com.microsoft.applicationinsights.diagnostics.collection.libos.os.linux.TwoStepProcReader;
 import java.io.File;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public class CGroupStatReader extends TwoStepProcReader {
   private final BigIncrementalCounter user = new BigIncrementalCounter();
   private final BigIncrementalCounter system = new BigIncrementalCounter();

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/cgroups/CGroupValueReader.java

@@ -7,7 +7,8 @@
 import com.microsoft.applicationinsights.diagnostics.collection.libos.os.linux.TwoStepProcReader;
 import java.io.File;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public abstract class CGroupValueReader extends TwoStepProcReader {
   private final BigIncrementalCounter usage = new BigIncrementalCounter();
 

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/cgroups/LinuxCGroupDataReader.java

@@ -10,7 +10,8 @@
 import java.nio.file.Files;
 import java.util.List;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public class LinuxCGroupDataReader implements CGroupDataReader {
 
   private static final String CGROUP_DIR = "/sys/fs/cgroup";

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/linux/cgroups/LinuxCGroupUsageDataReader.java

@@ -9,7 +9,8 @@
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public class LinuxCGroupUsageDataReader implements CGroupUsageDataReader {
 
   private final CGroupCpuUsageReader cgroupCpuUsageReader = new CGroupCpuUsageReader();

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/nop/NoOpCGroupDataReader.java

@@ -5,7 +5,10 @@
 
 import com.microsoft.applicationinsights.diagnostics.collection.libos.kernel.CGroupDataReader;
 
-@SuppressWarnings({"checkstyle:AbbreviationAsWordInName", "MemberName"})
+@SuppressWarnings({
+  "checkstyle:AbbreviationAsWordInName",
+  "MemberName"
+}) // CGroup is the standard abbreviation for Control Group
 public class NoOpCGroupDataReader implements CGroupDataReader {
 
   @Override

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/os/nop/NoOpCGroupUsageDataReader.java

@@ -8,7 +8,8 @@
 import java.util.List;
 import javax.annotation.Nullable;
 
-@SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+@SuppressWarnings(
+    "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control Group
 public class NoOpCGroupUsageDataReader implements CGroupUsageDataReader {
   @Override
   @Nullable

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/collection/libos/process/Process.java

@@ -6,7 +6,9 @@
 import com.microsoft.applicationinsights.diagnostics.collection.jvm.ProcessData;
 import com.microsoft.applicationinsights.diagnostics.collection.libos.TwoStepUpdatable;
 
-@SuppressWarnings({"JavaLangClash"})
+@SuppressWarnings({
+  "JavaLangClash"
+}) // name clash with java.lang is intentional and properly qualified
 public abstract class Process extends ProcessData implements TwoStepUpdatable {
 
   protected boolean isJava;

agent/agent-profiler/agent-diagnostics/src/main/java/com/microsoft/applicationinsights/diagnostics/jfr/CodeOptimizerDiagnosticsJfrInit.java

@@ -17,7 +17,7 @@
 import org.slf4j.LoggerFactory;
 
 /** Provides a JFR specific implementation of a diagnostics engine */
-@SuppressWarnings("Java8ApiChecker")
+@SuppressWarnings("Java8ApiChecker") // JFR APIs require Java 11+, but agent targets Java 8 bytecode
 public class CodeOptimizerDiagnosticsJfrInit {
 
   private static final Logger logger =
@@ -67,7 +67,9 @@ private static void logFailure(String logLine, @Nullable Exception e, AtomicInte
     count.incrementAndGet();
   }
 
-  @SuppressWarnings("checkstyle:AbbreviationAsWordInName")
+  @SuppressWarnings(
+      "checkstyle:AbbreviationAsWordInName") // CGroup is the standard abbreviation for Control
+  // Group
   public static void emitCGroupData() {
     try {
       CGroupData cgroupData = SystemStatsProvider.getCGroupData();