Blackbox

BlackBox is your project's Flight Recorder.

You know the moment- chat fills with “lag,” the server freezes for a few seconds, then everything goes back to normal. You check logs and find nothing useful. It is gone, it happened once, and nobody can reproduce it.

BlackBox fixes that.

It runs quietly in the background and, when a stall/spike/crash/oopsie happens, it captures a short window of evidence and writes a single incident bundle you can share or archive. You get answers after the fact, not only if you happen to be profiling at the exact right time.

How the game changes for you, the admin:

• Fewer blind restarts (you have a report)
• Faster fixes (one zip to hand to a developer)
• Less guesswork (incident timeline plus JVM evidence)
• Bounded disk usage (old logs deleted)

What you get:

• One zip per incident (consistent layout, easy to attach to tickets)
• report.html for humans (open locally, no ports required)
• recording.jfr for deep dives (JDK Mission Control)
• env snapshots (JVM and OS info)
• Optional Discord ping

Common use cases:

• “TPS dipped for 10 seconds”
• “Server froze, then recovered”
• “Random crash overnight”
• “Only one world lags, others are fine”
• “GC spikes under load” (if you do not know what this means, that is the point)

Install

1. Drop the jar into your server’s mods folder
2. Start the server
3. When something happens, open the newest incident zip and click report.html

Privacy and safety

Local by default. No uploads, no telemetry, no external services. Discord notifications are opt in and only send a short message (not the bundle). Log collection is optional.

Support:

https://discord.gg/kWFJbqkpfh