Перейти к содержимому
Mineforgian

PerfTriage

Automatically captures lag incidents on Fabric servers and points you to suspicious hotspot chunks.

Загрузки
182
Подписчики
1
Обновлён
3 мая 2026 г.
Лицензия
MIT

Опубликован 28 февраля 2026 г.

Сообщить об ошибке

⚡ PerfTriage – Automatic Lag Forensics for Fabric Servers

Fabric MC 1.21.4 Server Side Client Side Production Safe

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.

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

Ченджлог

1.7.0+mc1.21.4-2026-04-18Релиз1.21.4 · 18 апреля 2026 г.

PerfTriage 1.7.0

This update adds historical correlation to newly generated reports.

Added

  • Historical correlation analysis for new lag reports
  • Automatic matching against recent indexed incidents
  • Repeated hotspot type counts in report output
  • Repeated hotspot chunk counts in report output
  • Top historical matches included in both .txt and .json reports

New

  • Detection of repeated lag patterns across past incidents

  • Similar-event context directly inside newly generated reports

  • Correlation output for:

    • reason
    • entity hotspot type
    • block entity hotspot type
    • entity hotspot chunk
    • block entity hotspot chunk

Changed

  • Extended report generation to analyze recent indexed history before writing reports
  • Added history_correlation to the JSON report schema
  • Improved text reports with a dedicated HistoryCorrelation section

Improved

  • Easier identification of recurring lag incidents
  • Better visibility into repeated hotspot chunks and repeated hotspot types
  • More actionable reports without manually comparing multiple files

Notes

  • This update builds on the existing report index and summary system
  • No new trigger logic was added; the focus is recurring-incident recognition and historical context
1.6.0+mc1.21.4-2026-04-11Релиз1.21.4 · 11 апреля 2026 г.

PerfTriage 1.6.0

This update adds report history commands and indexed summary tools.

Added

  • /perftriage recent
  • /perftriage recent <limit>
  • /perftriage summary
  • /perftriage summary <limit>
  • Indexed report history reader built on top of index.jsonl

New

  • Recent incident listing directly in-game
  • Historical summary of indexed lag incidents
  • Breakdown of common reasons, worlds, hotspot entity types, and hotspot block entity types
  • Breakdown of frequently repeated hotspot chunks

Changed

  • Extended the command layer to expose report history from the existing incident index
  • Improved the usefulness of indexed reports by turning them into readable operational summaries
  • Made historical incident data directly accessible without opening report files manually

Improved

  • Faster review of recent lag events
  • Better visibility into repeated hotspot patterns
  • More practical long-term troubleshooting for live servers

Notes

  • This update builds on the existing report index introduced earlier
  • No new lag-capture trigger logic was added in this release; the focus is historical visibility and summary workflows
1.5.0+mc1.21.4-2026-04-04Релиз1.21.4 · 4 апреля 2026 г.

PerfTriage 1.5.0

This update focuses on the report pipeline and long-term server operation.

Added

  • Report index file at config/perftriage/reports/index.jsonl
  • Automatic report retention cleanup
  • Configurable report retention days
  • Configurable maximum report file count
  • Writer queue status in /perftriage status

Changed

  • Reworked the async report writer into a real bounded single-threaded queue
  • Improved report write ordering so report files, index updates, and cleanup run in sequence
  • Extended the config system with retention-related settings
  • Updated report generation flow to append incident summaries automatically

Improved

  • Better long-term behavior for servers that generate many reports
  • More predictable write/load behavior under repeated lag incidents
  • Reduced risk of unbounded background write buildup

Notes

  • This update is focused on report infrastructure rather than new lag-detection logic
  • Existing report generation behavior is preserved, while report history and cleanup are now handled automatically
1.4.0+mc1.21.4-2026-03-27Релиз1.21.4 · 27 марта 2026 г.

PerfTriage 1.4.0

A configuration-focused update that makes PerfTriage much easier to tune on live servers.

This release adds a proper config file and moves core detection / dump parameters out of hardcoded values and into user-editable settings.

New

  • config/perftriage/config.json
  • /perftriage reload
  • /perftriage config

Configurable settings

  • Trigger MSPT threshold
  • Trigger consecutive ticks
  • Recovery MSPT threshold
  • Recovery consecutive ticks
  • Auto-dump cooldown
  • World scan budget
  • Hotspot sample count
  • Hotspot Top-N size
  • Hotspot per-tick budget
  • Hotspot total budget
  • Text / JSON report output toggles

Why this matters PerfTriage is designed for real servers, and different servers need different sensitivity and scan budgets. This update makes the mod much more practical to deploy and tune without rebuilding the jar.

1.1.0+mc1.21.4-2026-03-01Релиз1.21.4 · 1 марта 2026 г.

fix wrong json output

Комментарии

Загружаем…