⬛ BlackBox

BlackBox 是一款面向 Paper 服务器的高级可观测性与诊断插件。
它持续记录服务器性能和活动,以便在发生卡顿、TPS 下降、崩溃或异常行为时,提供调查所需的信息,帮助你了解发生了什么、何时发生、何地发生以及当时正在运行什么。
BlackBox 不依赖单一的 TPS 数值,而是将性能指标、JVM 资源、区块、实体、服务器事件、插件、日志和实时 Java 分析数据整合到一个诊断系统中。
? 监控你的服务器
遥测数据会持续收集并异步写入,以最小化对主服务器线程的工作负担。

? 调查性能问题
当配置的 TPS 或刻时间阈值超出时,BlackBox 会自动检测性能事件。
对于每次事故,它可以分析:
- 问题开始和恢复的时间
- 最低 TPS 和最大刻时间
- 事故前、中、后的性能表现
- CPU、内存和 GC(垃圾回收)的变化
- 实体和区块的活动
- 服务器事件和热点
- 警告和异常
- JFR 分析证据
- 可能的原因及相关证据
BlackBox 区分直接证据和相关性,而不是自动归咎于某个插件、实体或区块。
? 查找热点
BlackBox 可以按世界和区块追踪活动,帮助你定位值得深入调查的区域。
它监控的事件包括:
- 实体的生成与移除
- 区块的加载与卸载
- 红石活动
- 漏斗和物品栏传输
- 活塞和爆炸
- 方块变化
- 刷怪笼和命令方块
- 强制加载区块和插件票证
可疑热点可以与高 MSPT 或低 TPS 时段相关联,并提供坐标以便在游戏中轻松检查。
? Java Flight Recorder
BlackBox 集成了 Java Flight Recorder (JFR) 以实现更深入的分析。
分析可以手动启动:
/blackbox profile 60
或者在 BlackBox 检测到重复的性能问题时自动启动。
JFR 分析可以提供关于以下内容的信息:
- CPU 采样和耗时方法
- 插件调用栈帧
- 垃圾回收
- 文件 I/O
- Socket I/O
- I/O 延迟
生成的 .jfr 文件也可以使用 IntelliJ Profiler 或 JDK Mission Control 打开以进行进一步调查。
? 插件、日志与崩溃诊断

BlackBox 会清点已安装的插件及其依赖项、命令、权限、监听器和计划任务。
它还监控服务器日志,并能识别与以下常见问题相关的内容:
- ⚙️ 配置
- ? 插件代码
- ? 依赖项和不兼容的版本
- ? 文件和权限
- ?️ 数据库
- ? 网络
- ☕ JVM 资源
- ⏱️
Can't keep up / 刻落后
- ? Watchdog 事件
还可以分析最近的崩溃报告,以识别根本异常、相关调用栈帧和常见的故障模式。
?️ 世界诊断
BlackBox 不仅能调查当前加载的区块。
其离线区域普查功能可以在不将区块加载到 Paper 中的情况下检查 Minecraft .mca 文件,检测有关存储区块、实体、方块实体、NBT 问题和区域结构的信息。
BlackBox 还可以分析命令方块和数据包函数,查找可能耗时的模式,如宽泛的选择器、重复召唤、大量粒子使用、forceload、大型 fill/clone 操作以及复杂的命令链。
? 详细报告

为任何可用的时间段生成诊断报告:
/blackbox report 30m
/blackbox report 6h
/blackbox report 2d
BlackBox 可以生成:
- ? 专业 PDF 报告
- ? 可搜索的 Markdown 报告
- ? 详细的 CSV 遥测数据
报告将性能、事件、CPU、内存、JVM 资源、热点、实体、插件、错误、JFR 分析、世界信息和其他证据整合到一份调查中。
BlackBox 还可以在服务器正常关闭时自动生成报告。
⌨️ 命令

| 命令 |
描述 |
/blackbox status |
显示最新的服务器健康信息 |
/blackbox scan |
排队执行完整的已加载区块扫描 |
/blackbox report <time> |
生成诊断报告 |
/blackbox profile <seconds> |
启动 Java Flight Recorder 分析 |
/bb |
/blackbox 的别名 |
权限: blackbox.admin
默认: OP
? 隐私
BlackBox 将诊断信息存储在本地服务器上。
根据你的配置,遥测数据可能包含玩家名称、UUID、位置、命令和错误信息。
隐私控制允许限制与玩家相关的信息,而网络地址可以哈希处理、明文存储或完全禁用。
BlackBox 的报告、分析和遥测数据应被视为私有的服务器运营数据。
⚙️ 兼容性

|
|
| 平台 |
Paper |
| Minecraft |
1.21.4 – 26.3 |
| 需要客户端模组 |
❌ 否 |
| 依赖项 |
❌ 无 |
| 仅服务端 |
✅ 是 |
? 安装
- 下载 BlackBox。
- 将
.jar 文件放入服务器的 plugins 文件夹中。
- 启动或重启服务器。
- 运行
/blackbox status。
- 完成!
BlackBox 旨在在整个服务器的生命周期内保持活跃,以便在出现问题时诊断证据已经存在。
⬛ 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
- Download BlackBox.
- Place the
.jar inside your server's plugins folder.
- Start or restart the server.
- Run
/blackbox status.
- That's it!
BlackBox is designed to remain active throughout the server's lifetime so that diagnostic evidence already exists when something goes wrong.
评论 0
登录后参与评分
还没有评论,来抢沙发吧