CheckLags
找出服务器卡顿的位置以及可能的原因。
spark 可以告诉你哪个插件或任务正在给服务器施加压力。但有时这只是部分情况。你可能知道实体或区块加载导致了问题,但仍然不知道具体发生在哪里。
这就是 CheckLags 旨在帮助解决的问题。
CheckLags 扫描已加载的区块,按预估的性能影响对它们进行排名,并让你了解每个热点中正在发生的事情。无论是刷怪塔、掉落的物品、大量的漏斗、方块实体还是频繁的区块加载,你都可以缩小值得调查的区域范围。
CheckLags 是什么?
CheckLags 是一个服务端诊断工具,帮助你追踪导致服务器性能问题的物理位置。
它在后台监控刻时间(tick times),并在检测到持续的 TPS 低下或异常的慢速刻时开始调查已加载的区块。
具体流程如下:
- CheckLags 使用 Paper 的
ServerTickEndEvent 测量刻持续时间。如果安装了 spark,则使用其 MSPT 统计数据作为额外参考。
- 当性能下降或刻时间出现尖峰时,CheckLags 开始扫描已加载的区块。
- 每个区块根据其内容(如实体、掉落物、方块实体和区块加载活动)获得一个相对热度评分。
- 结果被收集到一个排名列表中,以便你查看哪些区域值得调查。
当服务器正常运行时,扫描过程处于空闲状态。只有在需要调查性能问题时,它才会激活。
关于评分的说明: 区块热度只是一个估算值,并非区块实际消耗毫秒数的精确测量。Minecraft 和 Paper 分配刻工作的方式使得通过现有 API 无法可靠地进行单区块计时。
功能
卡顿热点
找到最可能导致服务器性能问题的区块。
/lagcheck top 显示热度最高的已加载区块,并按预估的影响程度排序。
- 点击结果可直接传送至对应位置。
/lagcheck watch 在你调查期间持续显示三个热度最高的区块。
- 每个热点都包含可能的解释,例如生物活动、物品堆积、方块实体或区块加载。
/lagcheck inspect 提供更详细的 3×3 区块区域视图,包括最常见的方块实体类型。
Folia 支持
CheckLags 使用同一个插件 jar 包支持 Paper、Purpur 和 Folia。
由于访问世界数据的方式不同,Folia 需要通过所属的区域线程来处理区块扫描。
额外的 Folia 功能包括:
- 运行时检测 Folia。
- 区域安全的区块扫描。
/lagcheck region 用于将当前区域的 TPS 与全局 TPS 进行比较。
- 在
/lagcheck top 的结果中同时显示区域 TPS 信息。
这使得更容易确定性能问题是影响整个服务器,还是集中在特定区域。
TPS 警报
当服务器性能低于配置的阈值时,CheckLags 可以通知工作人员。
- 默认警告阈值:18 TPS。
- 默认严重阈值:10 TPS。
- 独立的冷却时间可防止重复通知。
- 当 TPS 恢复正常时会发送恢复消息。
- 仅向拥有
checklags.alerts 权限的玩家发送警报。
警报故意不包含坐标或区块信息。这使得它们适合正在直播或共享屏幕且不希望暴露玩家基地的工作人员使用。
玩家也可以使用 /lagcheck alerts off 禁用自己的通知。
spark 集成
CheckLags 无需 spark 即可运行,但安装它能提供额外的性能信息。
当有 spark 可用时,CheckLags 会使用其公开统计 API 来获取更灵敏的 TPS 和 MSPT 读数。
启用 spark 集成后,/lagcheck stats 还可以显示:
- TPS 和 MSPT 统计数据。
- 进程和系统 CPU 使用情况。
- 垃圾回收活动和暂停信息。
- 尖峰计数和已加载区块信息。
这有助于区分由世界内活动引起的问题与与 CPU 使用率或垃圾回收相关的问题。
CheckLags 支持捆绑版 spark(包含在 Paper、Purpur 和 Folia 1.21+ 中)以及独立版 spark 插件,即使 spark 在 CheckLags 之后加载也能正常工作。
如果无法获取 spark,插件会自动回退到 Paper 的 tick API。活跃的数据源始终会在 /lagcheck stats 中显示。
命令
所有命令均使用 /lagcheck。同时也提供别名 /lags 和 /clag。
| 命令 |
说明 |
/lagcheck top [world] [rows] |
显示负载最高的区块以及当前 TPS。点击结果可传送至热点区域。 |
/lagcheck watch [seconds] |
持续显示前三大热点区域。默认持续时间为 120 秒。再次运行以停止。 |
/lagcheck inspect [world] [cx] [cz] |
扫描 3×3 区块区域,报告实体、物品、方块实体、区块加载情况、常见的方块实体类型以及导致强制加载区块的插件。若不提供参数,则使用你当前的位置。 |
/lagcheck region |
显示你所在区域的 TPS 与全局 TPS 的对比。仅限 Folia。 |
/lagcheck stats |
显示平台信息、spark 状态、TPS/MSPT、CPU 占用率、GC 活动、峰值次数和已加载区块数。 |
/lagcheck alerts [on|off] |
启用或禁用个人 TPS 通知。 |
/lagcheck reset |
清除热力图、刻历史数据和区块加载计数器。 |
/lagcheck reload |
在不重启服务器的情况下重新加载配置。 |

权限
| 权限 |
说明 |
checklags.use |
访问诊断命令(top、watch、inspect、region、stats)。默认:OP。 |
checklags.admin |
访问 reset 和 reload。默认:OP。 |
checklags.alerts |
接收 TPS 下降和恢复的通知。默认:OP。 |
仅需调查性能问题的员工可以仅被授予 checklags.use 权限,而无需获得重置诊断数据或更改配置的权限。
警报偏好设置命令和帮助无需额外权限即可使用。
配置
配置文件位于:
plugins/CheckLags/config.yml
其中包含 CheckLags 使用的阈值、扫描间隔和权重评分。
以下是最可能需要调整的设置:
spike-threshold-ms: 50
tps-alert-threshold: 18.0
census-interval-ticks: 40
heat-decay: 0.9
weights:
block-entity: 2.0
hostile-mob: 1.0
item: 0.5
chunk-load: 8.0
调整权重的几个示例:
- 如果你的服务器有大量红石、漏斗或其他方块实体活动,请增加
block-entity 的值。
- 如果掉落物是常见问题,请增加
item 的值。
- 如果怪物密集的区域导致卡顿,请调整
hostile-mob 的值。
chunk-load 的默认权重故意设得较高,以便更容易发现频繁的区块加载活动。
最佳数值取决于你的服务器以及导致性能问题的活动类型。
重要提示
使用 CheckLags 时,有几件事值得注意:
- 区块热度是相对的。 它有助于识别值得调查的区域,但在需要详细计时数据时,它不能替代 spark 分析器。
- 实体分类不包括玩家。 宠物和农场动物的权重也低于敌对怪物。
- 手动刻控制期间扫描暂停。 当
/tick freeze、/tick step、/tick sprint 或自定义刻速率处于活动状态时,检测和扫描将禁用。这些条件会扭曲正常的刻测量值。
- 区块加载活动使用滚动 60 秒窗口。 频繁加载活动的区块将获得更高的分数。
- 仅限 Paper 系列服务器。 不支持 Bukkit 和 Spigot,因为 CheckLags 依赖 Paper API 功能及其 API 版本要求。
你可以查看 /lagcheck stats 以了解扫描是否当前暂停以及哪个统计源处于活动状态。
反馈与问题
CheckLags 由 Mr_Nova_76 开发。
如果你发现错误或有新功能的想法,欢迎通过 Discord 联系我:Mr_Nova_76。
始终欢迎提供反馈和建议。
如果你觉得 CheckLags 有用,请考虑关注它或与其它服务器所有者分享。这对项目真的很有帮助!
CheckLags
Find out where your server is lagging and what might be causing it.
spark can tell you which plugin or task is putting pressure on your server. But sometimes that's only half the picture. You might know that entities or chunk loading are causing problems, but still have no idea where it's happening.
That's what CheckLags is designed to help with.
CheckLags scans loaded chunks, ranks them by estimated lag impact, and gives you an idea of what's happening in each hotspot. Whether it's a mob farm, dropped items, a large number of hoppers, block entities, or frequent chunk loading, you can narrow down the areas worth investigating.
What is CheckLags?
CheckLags is a server-side diagnostic tool that helps you track down the physical locations behind server performance issues.
It monitors tick times in the background and starts investigating loaded chunks when it detects sustained low TPS or unusually slow ticks.
Here's what happens:
- CheckLags measures tick duration using Paper's
ServerTickEndEvent. If spark is available, its MSPT statistics are used as an additional reference.
- When performance drops or tick spikes occur, CheckLags starts scanning loaded chunks.
- Each chunk receives a relative heat score based on its contents, such as entities, dropped items, block entities, and chunk-loading activity.
- Results are collected into a ranked list so you can see which areas are worth investigating.
When the server is running normally, the scanning process stays idle. It only becomes active when there's a performance issue to investigate.
A note about the scores: Chunk heat is an estimate, not an exact measurement of how many milliseconds a chunk consumes. Minecraft and Paper distribute tick work in ways that don't allow reliable per-chunk timing through the available APIs.
Features
Lag hotspots
Find the chunks that are most likely contributing to your server's performance problems.
/lagcheck top displays the hottest loaded chunks, ranked by their estimated impact.
- Click a result to teleport directly to the corresponding location.
/lagcheck watch continuously displays the three hottest chunks while you investigate.
- Each hotspot includes a possible explanation, such as mob activity, item accumulation, block entities, or chunk loading.
/lagcheck inspect provides a closer look at a 3×3 chunk area, including its most common block-entity types.
Folia support
CheckLags supports Paper, Purpur, and Folia using the same plugin jar.
Folia requires a different approach to accessing world data, so chunk scanning is handled through the owning region thread.
Additional Folia features include:
- Runtime detection of Folia.
- Region-safe chunk scanning.
/lagcheck region to compare your current region's TPS with global TPS.
- Region TPS information displayed alongside chunk results in
/lagcheck top.
This makes it easier to identify whether performance issues affect the entire server or are concentrated in a particular region.
TPS alerts
CheckLags can notify staff when server performance drops below configured thresholds.
- Default warning threshold: 18 TPS.
- Default critical threshold: 10 TPS.
- Separate cooldowns prevent repeated notifications.
- A recovery message is sent when TPS returns to normal.
- Alerts are sent only to players with
checklags.alerts.
Alerts intentionally contain no coordinates or chunk information. This makes them suitable for staff who are streaming or sharing their screen and don't want to expose player bases.
Players can also disable their own notifications with /lagcheck alerts off.
spark integration
CheckLags works without spark, but having it installed provides additional performance information.
When spark is available, CheckLags uses its public statistics API for more responsive TPS and MSPT readings.
With spark integration, /lagcheck stats can also display:
- TPS and MSPT statistics.
- Process and system CPU usage.
- Garbage collection activity and pause information.
- Spike count and loaded chunk information.
This can help distinguish between problems caused by activity inside the world and issues related to CPU usage or garbage collection.
CheckLags supports both bundled spark (included with Paper, Purpur, and Folia 1.21+) and the standalone spark plugin, including cases where spark loads after CheckLags.
If spark isn't available, the plugin automatically falls back to Paper's tick APIs. The active statistics source is always shown in /lagcheck stats.
Commands
All commands use /lagcheck. The aliases /lags and /clag are also available.
| Command |
Description |
/lagcheck top [world] [rows] |
Displays the hottest loaded chunks, along with current TPS. Results can be clicked to teleport to a hotspot. |
/lagcheck watch [seconds] |
Continuously displays the top three hotspots. Default duration is 120 seconds. Run again to stop. |
/lagcheck inspect [world] [cx] [cz] |
Scans a 3×3 chunk area and reports entities, items, block entities, chunk loads, common block-entity types, and plugins responsible for force-loaded chunks. Without arguments, uses your current location. |
/lagcheck region |
Shows the TPS of your current region compared with global TPS. Folia only. |
/lagcheck stats |
Displays platform information, spark status, TPS/MSPT, CPU usage, GC activity, spike count, and loaded chunks. |
/lagcheck alerts [on|off] |
Enables or disables personal TPS notifications. |
/lagcheck reset |
Clears the heat map, tick history, and chunk-load counters. |
/lagcheck reload |
Reloads the configuration without restarting the server. |

Permissions
| Permission |
Description |
checklags.use |
Access to diagnostic commands (top, watch, inspect, region, stats). Default: OP. |
checklags.admin |
Access to reset and reload. Default: OP. |
checklags.alerts |
Receives TPS drop and recovery notifications. Default: OP. |
Staff members who only need to investigate performance issues can be given checklags.use without receiving permission to reset diagnostic data or change the configuration.
The alerts preference commands and help are available without additional permission requirements.
Configuration
The configuration file is located at:
plugins/CheckLags/config.yml
It contains the thresholds, scan intervals, and scoring weights used by CheckLags.
The following settings are the ones you're most likely to adjust:
spike-threshold-ms: 50
tps-alert-threshold: 18.0
census-interval-ticks: 40
heat-decay: 0.9
weights:
block-entity: 2.0
hostile-mob: 1.0
item: 0.5
chunk-load: 8.0
A few examples of how to tune the weights:
- Increase
block-entity if your server has a lot of redstone, hoppers, or other block-entity activity.
- Increase
item if dropped items are a common problem.
- Adjust
hostile-mob if mob-heavy areas are contributing to lag.
chunk-load has a deliberately high default weight to make frequent chunk-loading activity easier to spot.
The best values depend on your server and the type of activity causing its performance problems.
Important notes
There are a few things worth keeping in mind when using CheckLags:
- Chunk heat is relative. It helps identify areas worth investigating, but it doesn't replace a spark profiler when you need detailed timings.
- Entity classification excludes players. Pets and farm animals also have lower weights than hostile mobs.
- Scanning pauses during manual tick control. Detection and scanning are disabled while
/tick freeze, /tick step, /tick sprint, or a custom tick rate is active. These conditions can distort normal tick measurements.
- Chunk-load activity uses a rolling 60-second window. Chunks with frequent loading activity will receive a higher score.
- Paper-family servers only. Bukkit and Spigot are not supported because CheckLags relies on Paper API features and its API version requirements.
You can check /lagcheck stats to see whether scanning is currently paused and which statistics source is active.
Feedback and issues
CheckLags is developed by Mr_Nova_76.
If you find a bug or have an idea for a new feature, feel free to get in touch with me on Discord: Mr_Nova_76.
Feedback and suggestions are always welcome.
If you find CheckLags useful, consider leaving a follow or sharing it with other server owners. It really helps the project!
评论 0
登录后参与评分
还没有评论,来抢沙发吧