⚡ 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.

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

PerfTriage vs spark

PerfTriage is not a replacement for full profilers like spark.

They solve different problems.

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

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.

This mod updates weekly, maybe one or two times a week.