Package com.ultikits.ultitools.manager

Class ErrorReportCollector

java.lang.Object

com.ultikits.ultitools.manager.ErrorReportCollector

@Internal
public class ErrorReportCollector
extends Object

Collects, deduplicates, and rate-limits error reports before they reach the WebSocket.

Three-layer protection against DB bloat: 1. Fingerprint dedup within 5-minute window 2. Max 10 unique errors per batch cycle 3. Sampling after 10 total occurrences of same error

This class NEVER uses java.util.logging.Logger to prevent circular logging. All internal error output uses System.err.

Since:

6.2.3

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	ErrorReportCollector.ErrorReport	Error report data structure.

Field Summary

Fields

Modifier and Type	Field	Description
private final ConcurrentHashMap<String,ErrorReportCollector.ErrorReport>	dedupMap
private int	dedupWindowSeconds
private boolean	enabled
private final ConcurrentLinkedQueue<ErrorReportCollector.ErrorReport>	errorQueue
private static final int	FINGERPRINT_STACK_FRAMES
private final ConcurrentHashMap<String,AtomicInteger>	lifetimeCounters
private static final int	MAX_MESSAGE_LENGTH
private static final int	MAX_QUEUE_SIZE
private static final int	MAX_STACK_FRAMES
private static final int	MAX_STACK_TRACE_LENGTH
private int	maxErrorsPerBatch
private int	sampleAfterCount
private double	sampleRate
private ScheduledExecutorService	scheduler

Constructor Summary

Constructors

Constructor	Description
ErrorReportCollector()

Method Summary

Modifier and Type	Method	Description
private void	captureServerState(ErrorReportCollector.ErrorReport report)	Capture current server state (TPS, memory, player count).
private String	computeFingerprint(Throwable throwable)	Compute a fingerprint for dedup: hash of (exception class + top N stack frame method:line).
private boolean	computeIsFramework(Throwable throwable, String moduleName)	Determine whether an error originates from the UltiTools framework itself (as opposed to a plugin module loaded by the framework).
private ErrorReportCollector.ErrorReport	createReport(Throwable throwable, String fingerprint, String moduleName, TriggerContext ctx)	Create an ErrorReport from a throwable.
com.google.gson.JsonArray	drainErrors(int max)	Drain errors into a JsonArray for batch_update.
private String	formatStackTrace(Throwable throwable)	Format stack trace to string, truncated to MAX_STACK_TRACE_LENGTH.
void	init()	Initialize the collector and start the dedup window reset scheduler.
boolean	isEnabled()	Check if error reporting is enabled.
void	loadConfiguration()	Load configuration from UltiTools config.yml.
void	reportError(Throwable throwable, String moduleName, TriggerContext ctx)	Report an error.
private void	resetDedupWindow()	Reset the dedup window — allows the same error to be reported again.
void	shutdown()	Shutdown the collector.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

MAX_QUEUE_SIZE

private static final int MAX_QUEUE_SIZE

See Also:

• Constant Field Values

MAX_MESSAGE_LENGTH

private static final int MAX_MESSAGE_LENGTH

See Also:

• Constant Field Values

MAX_STACK_TRACE_LENGTH

private static final int MAX_STACK_TRACE_LENGTH

See Also:

• Constant Field Values

MAX_STACK_FRAMES

private static final int MAX_STACK_FRAMES

See Also:

• Constant Field Values

FINGERPRINT_STACK_FRAMES

private static final int FINGERPRINT_STACK_FRAMES

See Also:

• Constant Field Values

enabled

private volatile boolean enabled

dedupWindowSeconds

private volatile int dedupWindowSeconds

maxErrorsPerBatch

private volatile int maxErrorsPerBatch

sampleAfterCount

private volatile int sampleAfterCount

sampleRate

private volatile double sampleRate

dedupMap

private final ConcurrentHashMap<String,ErrorReportCollector.ErrorReport> dedupMap

errorQueue

private final ConcurrentLinkedQueue<ErrorReportCollector.ErrorReport> errorQueue

lifetimeCounters

private final ConcurrentHashMap<String,AtomicInteger> lifetimeCounters

scheduler

private ScheduledExecutorService scheduler

Constructor Details

ErrorReportCollector

public ErrorReportCollector()

Method Details

init

public void init()

Initialize the collector and start the dedup window reset scheduler.

shutdown

public void shutdown()

Shutdown the collector.

loadConfiguration

public void loadConfiguration()

Load configuration from UltiTools config.yml.

reportError

public void reportError(Throwable throwable,
 String moduleName,
 TriggerContext ctx)

Report an error. Thread-safe. Returns immediately if disabled.

Parameters:

throwable - the exception

moduleName - which UltiTools module caused it (e.g., "UltiChat")

ctx - trigger context (who/what caused this)

drainErrors

public com.google.gson.JsonArray drainErrors(int max)

Drain errors into a JsonArray for batch_update. Layer 2: returns at most maxErrorsPerBatch, sorted by count descending. Performs a final dedup pass to merge entries with the same fingerprint.

Parameters:

max - maximum number of errors to drain

Returns:

JsonArray of error reports

resetDedupWindow

private void resetDedupWindow()

Reset the dedup window — allows the same error to be reported again.

computeFingerprint

private String computeFingerprint(Throwable throwable)

Compute a fingerprint for dedup: hash of (exception class + top N stack frame method:line).

createReport

private ErrorReportCollector.ErrorReport createReport(Throwable throwable,
 String fingerprint,
 String moduleName,
 TriggerContext ctx)

Create an ErrorReport from a throwable.

captureServerState

private void captureServerState(ErrorReportCollector.ErrorReport report)

Capture current server state (TPS, memory, player count).

formatStackTrace

private String formatStackTrace(Throwable throwable)

Format stack trace to string, truncated to MAX_STACK_TRACE_LENGTH.

computeIsFramework

private boolean computeIsFramework(Throwable throwable,
 String moduleName)

Determine whether an error originates from the UltiTools framework itself (as opposed to a plugin module loaded by the framework).

A framework error satisfies BOTH: 1. The top stack frame's class is in the com.ultikits.ultitools package. 2. The module name indicates the framework (null, empty, or "UltiTools").

isEnabled

public boolean isEnabled()

Check if error reporting is enabled.

Returns:

true if enabled