⚡ PerfTriage – Automatic Lag Forensics for Fabric Servers

Catch lag when it happens — automatically

PerfTriage is a lightweight server-side lag triage mod for Fabric.

It stays quiet during normal gameplay. When your server hits sustained MSPT spikes, it automatically captures a structured diagnostic snapshot of what was loaded, where it was concentrated, and which chunks are most suspicious.

It is built for one practical question:

When lag happened, what exactly was going on?

Why install PerfTriage?

Most server lag does not happen while you are actively profiling.

By the time players report:

“the server froze”
“something is wrong in one area”
“TPS dropped again”

…the moment is often already gone.

PerfTriage is designed for that exact problem.

Instead of running as a heavy always-on profiler, it waits for meaningful lag spikes, then records a focused report so you still have evidence after the incident.

text report shows MSPT avg / p95 / max , top entity types

What PerfTriage detects

PerfTriage monitors:

Sustained MSPT spikes
Automatic recovery after lag
Cooldown-based dump throttling
Hard scan budget protection

When triggered, it generates a structured report with:

Tick analysis

Windowed MSPT statistics (avg / p95 / max)
Sampling duration
Budget usage
Scan truncation status

World snapshot

Loaded chunk count per dimension
Total entities / block entities
Top entity types
Top block entity types

Hotspot analysis

Dominant entity type
Dominant block entity type
Chunk-level concentration
Average population per tick
Budget information
Chunk scan capability flag

Reports are written asynchronously to:

config/perftriage/reports/

Both:

.txt for humans
.json for tools

Why hotspot chunks matter

Lag is often caused by local concentration, not just global load.

Typical examples include:

Item / mob / boat flooding
Redstone machines
Mob farms
Sculk farms
Chunk loaders
Misbehaving contraptions concentrated in a few chunks

PerfTriage does not only tell you what was loaded. It tells you where the concentration was.

That means you can:

teleport directly to the problem area
inspect the affected chunks
remove the source
verify the improvement immediately

text report shows entity_hot_type , entity_hot_chunks_topN

PerfTriage vs spark

PerfTriage is not a replacement for full profilers like spark.

They solve different problems.

Tool	Best for	Typical workflow
PerfTriage	Automatically catching lag incidents	Install and wait for spikes
spark	Deep profiling and root-cause investigation	Run manually when needed
Both together	Catch first, investigate later	Best overall workflow

PerfTriage is for automatic incident capture. spark is for deeper profiling after you know where to look.

That is why they work well together.

Who should install this?

PerfTriage is especially useful for:

server owners who only notice lag after players complain
admins who need chunk coordinates, not just “the server is slow”
production servers where always-on profiling is undesirable
servers with intermittent lag that is hard to reproduce manually

compare PerfTriage with Spark

What makes it different?

PerfTriage does not continuously instrument tick functions.

Instead, it focuses on:

activating only during meaningful lag
using strict scan and sampling budgets
avoiding heavy background overhead
producing deterministic snapshots
providing chunk-level localization

This makes it suitable for real servers where stability matters.

Commands

Manual dump

/perftriage dump now

Status

/perftriage status

Displays:

current MSPT window stats
cooldown remaining
last report path
recovery state

Example hotspot output

entity_hot_type: minecraft:acacia_boat
entity_hot_chunks_topN:
  - -4,-4: 35320
  - -4,-3: 35280
  - -5,-3: 31600

This means most of the detected hotspot population is concentrated in those chunks.

Compatibility

Fabric Loader 0.18+
Minecraft 1.21.4
Server-side

Philosophy

PerfTriage focuses on:

low overhead
deterministic diagnostics
automatic operation
production safety

It is designed to help you keep evidence when lag happens, instead of forcing you to guess after the fact.

Roadmap

Multi-version support (1.20.x / 1.21.x)
Optional Top-K type chunk breakdown
Configurable thresholds
Report index aggregation
Optional profiler integration mode

License

MIT

Built for real servers. Designed for real lag.

PerfTriage