Runtime Error Diagnostics

The ErrorTracker listens to ScriptContext.Error on the server and receives forwarded errors from the Client SDK. Instead of logging every duplicate error from broken loops, it deduplicates errors by callstack and uses step throttling to avoid flooding output and HTTP rate limits.

---

Architecture Flow

flowchart TD
    subgraph Roblox Engine
        A[Server Scripts] -->|ScriptContext.Error| C[ErrorTracker]
        B[Client LocalScripts] -->|Client SDK Bridge| C
    end

    subgraph Normalization & Throttling
        C --> D[Normalize & Strip Line Specifics]
        D --> E[Compute Fingerprint Hash]
        E --> F{Seen Before?}
        F -->|Occurrence #1| G[Dispatch Event Immediately]
        F -->|Occurrence #2-4| H[Drop Event]
        F -->|Occurrence #5, 10, 25, 50, 100| G
        F -->|Every 100th thereafter| G
    end

    subgraph Export Pipeline
        G --> I[Roblox Analytics / HTTP Webhooks / Console]
    end

---

Dispatched Event: RuntimeError

Whenever an error is captured and passes throttle filtering, a RuntimeError event is dispatched:

{
  "name": "RuntimeError",
  "category": "error",
  "timestamp": 1727790000,
  "userId": 12345678,
  "data": {
    "errorMessage": "attempt to index nil with 'Character'",
    "stackTrace": "ServerScriptService.CombatSystem:42\nServerScriptService.DamageHandler:88",
    "scriptName": "ServerScriptService.CombatSystem",
    "totalOccurrences": 5
  }
}

---

Throttling Logic

A broken Heartbeat connection can fire 60 times a second. Emitting an event for each repetition would burn through Roblox’s 500 requests/minute HTTP limit in seconds.

To prevent this, ErrorTracker groups errors by callstack signature and only emits events on specific occurrence milestones:

Occurrence	Action	Purpose
1st	Dispatched immediately	Instant notice of a new error
2nd – 4th	Suppressed	Absorbs fast duplicate bursts
5th	Dispatched (totalOccurrences: 5)	Confirms error is recurring
10th, 25th, 50th	Dispatched	Milestone check-in
100th+	Dispatched every 100th occurrence	Tracks long-term severity without spam

---

Console Output Example

When debugMode = true, errors print directly in the Studio output:

[RealisticAnalytics] --- Batch of 1 Event(s) ---
  [1] (error) RuntimeError [User: 201989656] -> {
   "errorMessage": "Players.iiRealistic_Dev.PlayerGui.ShopGui.LocalScript:15: attempt to index nil with 'Price'",
   "scriptName": "ShopGui.LocalScript",
   "totalOccurrences": 1
 }
[RealisticAnalytics] ---------------------------------------------

---

Configuration

Enable or disable automatic error tracking in AnalyticsModule.init:

local Analytics = AnalyticsModule.init({
    autoTrackErrors = true, -- Default: true
})