BlackBox - Server Diagnostics

⬛ BlackBox

BlackBox is an advanced observability and diagnostics plugin for Paper servers.

It continuously records server performance and activity so that when lag, TPS drops, crashes or unexpected behaviour happen, you have the information needed to investigate what happened, when it happened, where it happened and what was happening at the same time.

Instead of relying on a single TPS number, BlackBox connects performance metrics, JVM resources, chunks, entities, server events, plugins, logs and real Java profiles into one diagnostic system.

🔍 Monitor Your Server

Telemetry is collected continuously and written asynchronously to minimize work on the main server thread.

📉 Investigate Performance Problems

BlackBox automatically detects performance episodes when configured TPS or tick-time thresholds are exceeded.

For each incident, it can analyze:

• When the problem started and recovered
• Minimum TPS and maximum tick time
• Performance before, during and after the incident
• CPU, memory and GC changes
• Entity and chunk activity
• Server events and hotspots
• Warnings and exceptions
• JFR profiling evidence
• Possible causes and supporting evidence

BlackBox distinguishes between direct evidence and correlation instead of automatically blaming a plugin, entity or chunk.

📍 Find Hotspots

BlackBox can track activity by world and chunk, helping you locate areas that deserve investigation.

It monitors events such as:

• Entity spawns and removals
• Chunk loads and unloads
• Redstone activity
• Hopper and inventory transfers
• Pistons and explosions
• Block changes
• Spawners and command blocks
• Forced chunks and plugin tickets

Suspicious hotspots can be correlated with periods of high MSPT or low TPS, including coordinates that make them easy to inspect in-game.

🔥 Java Flight Recorder

BlackBox integrates with Java Flight Recorder (JFR) for deeper profiling.

Profiles can be started manually:

/blackbox profile 60

Or automatically when BlackBox detects repeated performance problems.

JFR analysis can provide information about:

• CPU samples and expensive methods
• Plugin stack frames
• Garbage collection
• File I/O
• Socket I/O
• I/O latency

Generated .jfr files can also be opened with IntelliJ Profiler or JDK Mission Control for further investigation.

🧩 Plugin, Log & Crash Diagnostics

BlackBox inventories installed plugins and their dependencies, commands, permissions, listeners and scheduled tasks.

It also monitors server logs and recognizes common problems related to:

• ⚙️ Configuration
• 🧩 Plugin code
• 🔗 Dependencies and incompatible versions
• 📁 Files and permissions
• 🗄️ Databases
• 🌐 Networking
• ☕ JVM resources
• ⏱️ Can't keep up / ticks behind
• 💥 Watchdog events

Recent crash reports can also be analyzed to identify root exceptions, relevant stack frames and common failure patterns.

🗺️ World Diagnostics

BlackBox can investigate more than just currently loaded chunks.

Its offline region census can inspect Minecraft .mca files without loading their chunks into Paper, detecting information about stored chunks, entities, block entities, NBT problems and region structure.

BlackBox can also analyze command blocks and datapack functions for potentially expensive patterns such as broad selectors, repeated summons, heavy particle usage, forceload, large fill/clone operations and complex command chains.

📊 Detailed Reports

Generate a diagnostic report for any available time window:

/blackbox report 30m

/blackbox report 6h

/blackbox report 2d

BlackBox can generate:

• 📕 Professional PDF reports
• 📝 Searchable Markdown reports
• 📊 Detailed CSV telemetry

Reports combine performance, incidents, CPU, memory, JVM resources, hotspots, entities, plugins, errors, JFR profiles, world information and other evidence into a single investigation.

BlackBox can also automatically generate a report when the server shuts down normally.

⌨️ Commands

Command	Description
/blackbox status	Shows the latest server health information
/blackbox scan	Queues a complete loaded-chunk scan
/blackbox report <time>	Generates a diagnostic report
/blackbox profile <seconds>	Starts a Java Flight Recorder profile
/bb	Alias for /blackbox

Permission: blackbox.admin
Default: OP

🔐 Privacy

BlackBox stores diagnostic information locally on your server.

Depending on your configuration, telemetry may contain player names, UUIDs, locations, commands and error information.

Privacy controls allow player-related information to be limited, while network addresses can be hashed, stored plainly or disabled entirely.

BlackBox reports, profiles and telemetry should be treated as private server operational data.

⚙️ Compatibility

Platform	Paper
Minecraft	1.21.4 – 26.3
Client mod required	❌ No
Dependencies	❌ None
Server-side	✅ Yes

🚀 Installation

1. Download BlackBox.
2. Place the .jar inside your server's plugins folder.
3. Start or restart the server.
4. Run /blackbox status.
5. That's it!

BlackBox is designed to remain active throughout the server's lifetime so that diagnostic evidence already exists when something goes wrong.