From 1c85c7c8ed59ba9d9bedf94c7dbb6b95ce0a8ce0 Mon Sep 17 00:00:00 2001
From: david <mail@nonswag.dev>
Date: Wed, 25 Mar 2026 18:46:15 +0100
Subject: [PATCH] Add handled error tracking to `ErrorTracker`

Introduced `handled` parameter to `trackError` methods for more accurate error categorization. Updated `compile` method in `ErrorHelper` to include the `handled` field and adjusted related implementations.
---
 .../faststats/bukkit/PaperEventListener.java  |  2 +-
 .../java/dev/faststats/core/ErrorHelper.java  |  3 +-
 .../java/dev/faststats/core/ErrorTracker.java | 35 ++++++++++++++++---
 .../faststats/core/SimpleErrorTracker.java    | 18 +++++++---
 gradle.properties                             |  2 +-
 5 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/bukkit/src/main/java/dev/faststats/bukkit/PaperEventListener.java b/bukkit/src/main/java/dev/faststats/bukkit/PaperEventListener.java
index c8e775d..2f2448e 100644
--- a/bukkit/src/main/java/dev/faststats/bukkit/PaperEventListener.java
+++ b/bukkit/src/main/java/dev/faststats/bukkit/PaperEventListener.java
@@ -12,6 +12,6 @@ public void onServerException(final ServerExceptionEvent event) {
         if (!(event.getException() instanceof final ServerPluginException exception)) return;
         if (!exception.getResponsiblePlugin().equals(metrics.plugin())) return;
         final var report = exception.getCause() != null ? exception.getCause() : exception;
-        metrics.getErrorTracker().ifPresent(tracker -> tracker.trackError(report));
+        metrics.getErrorTracker().ifPresent(tracker -> tracker.trackError(report, false));
     }
 }
diff --git a/core/src/main/java/dev/faststats/core/ErrorHelper.java b/core/src/main/java/dev/faststats/core/ErrorHelper.java
index 1972777..ebecb3e 100644
--- a/core/src/main/java/dev/faststats/core/ErrorHelper.java
+++ b/core/src/main/java/dev/faststats/core/ErrorHelper.java
@@ -17,7 +17,7 @@ final class ErrorHelper {
     private static final int STACK_TRACE_LENGTH = Math.min(500, Integer.getInteger("faststats.stack-trace-length", 300));
     private static final int STACK_TRACE_LIMIT = Math.min(50, Integer.getInteger("faststats.stack-trace-limit", 15));
 
-    public static JsonObject compile(final Throwable error, @Nullable final List<String> suppress) {
+    public static JsonObject compile(final Throwable error, @Nullable final List<String> suppress, final boolean handled) {
         final var report = new JsonObject();
         final var message = getAnonymizedMessage(error);
 
@@ -40,6 +40,7 @@ public static JsonObject compile(final Throwable error, @Nullable final List<Str
         if (message != null) report.addProperty("message", message);
 
         report.add("stack", stacktrace);
+        report.addProperty("handled", true);
 
         return report;
     }
diff --git a/core/src/main/java/dev/faststats/core/ErrorTracker.java b/core/src/main/java/dev/faststats/core/ErrorTracker.java
index 4108a2a..478b4d8 100644
--- a/core/src/main/java/dev/faststats/core/ErrorTracker.java
+++ b/core/src/main/java/dev/faststats/core/ErrorTracker.java
@@ -21,8 +21,8 @@ public sealed interface ErrorTracker permits SimpleErrorTracker {
      *
      * @return the error tracker
      * @see #contextUnaware()
-     * @see #trackError(String)
-     * @see #trackError(Throwable)
+     * @see #trackError(String, boolean)
+     * @see #trackError(Throwable, boolean)
      * @since 0.10.0
      */
     @Contract(value = " -> new")
@@ -51,24 +51,51 @@ static ErrorTracker contextUnaware() {
     }
 
     /**
-     * Tracks an error.
+     * Tracks a handled  error.
      *
      * @param message the error message
      * @see #trackError(Throwable)
+     * @see #trackError(String, boolean)
      * @since 0.10.0
      */
     @Contract(mutates = "this")
     void trackError(String message);
 
     /**
-     * Tracks an error.
+     * Tracks a handled error.
      *
      * @param error the error
+     * @see #trackError(Throwable, boolean)
      * @since 0.10.0
      */
     @Contract(mutates = "this")
     void trackError(Throwable error);
 
+    /**
+     * Tracks an error.
+     * <p>
+     * A {@code handled=true} error is expected and properly handled.
+     *
+     * @param message the error message
+     * @param handled whether the error was handled
+     * @see #trackError(Throwable, boolean)
+     * @since 0.20.0
+     */
+    @Contract(mutates = "this")
+    void trackError(String message, boolean handled);
+
+    /**
+     * Tracks an error.
+     * <p>
+     * A {@code handled=true} error is expected and properly handled.
+     *
+     * @param error   the error
+     * @param handled whether the error was handled
+     * @since 0.20.0
+     */
+    @Contract(mutates = "this")
+    void trackError(Throwable error, boolean handled);
+
     /**
      * Attaches an error context to the tracker.
      * <p>
diff --git a/core/src/main/java/dev/faststats/core/SimpleErrorTracker.java b/core/src/main/java/dev/faststats/core/SimpleErrorTracker.java
index 4fdbb7a..e10165d 100644
--- a/core/src/main/java/dev/faststats/core/SimpleErrorTracker.java
+++ b/core/src/main/java/dev/faststats/core/SimpleErrorTracker.java
@@ -19,13 +19,23 @@ final class SimpleErrorTracker implements ErrorTracker {
 
     @Override
     public void trackError(final String message) {
-        trackError(new RuntimeException(message));
+        trackError(message, true);
     }
 
     @Override
     public void trackError(final Throwable error) {
+        trackError(error, true);
+    }
+
+    @Override
+    public void trackError(final String message, final boolean handled) {
+        trackError(new RuntimeException(message), handled);
+    }
+
+    @Override
+    public void trackError(final Throwable error, final boolean handled) {
         try {
-            final var compiled = ErrorHelper.compile(error, null);
+            final var compiled = ErrorHelper.compile(error, null, handled);
             final var hashed = MurmurHash3.hash(compiled);
             if (collected.compute(hashed, (k, v) -> {
                 return v == null ? 1 : v + 1;
@@ -84,9 +94,9 @@ public synchronized void attachErrorContext(@Nullable final ClassLoader loader)
                 if (loader != null && !ErrorTracker.isSameLoader(loader, error)) return;
                 final var event = errorEvent;
                 if (event != null) event.accept(loader, error);
-                trackError(error);
+                trackError(error, false);
             } catch (final Throwable t) {
-                trackError(t);
+                trackError(t, false);
             }
         });
     }
diff --git a/gradle.properties b/gradle.properties
index 8fa71c1..a4c13e0 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -1 +1 @@
-version=0.19.0
+version=0.20.0