MeowMC

/meow profiler

/meow profiler start [--only <world|thread>]
/meow profiler stop
/meow profiler status

Permission: bukkit.command.meowmc.profiler.

profiler runs a sampling session: start arms it, stop closes it and writes the report artifact, status reports the running (or last) session.

start

| Form | Scope | Records | | --- | --- | --- | | /meow profiler start | all | World sampling and per-thread CPU. | | /meow profiler start --only world | world | World sampling only. No thread segment. | | /meow profiler start --only thread | thread | The thread segment only. |

Two preconditions, each answered with a refusal that names the real cause:

  • The JVM must report per-thread CPU time (ThreadMXBean) for any scope that records threads. On a JVM that does not, --only thread is refused outright and start (scope all) falls back with the reason; --only world always works.
  • profiling.support-cpu-time must be true in config/meowmc-global.yml for the thread segment — the refusal names the key and the file.

Only one session runs at a time; a second start answers that a session is already running and reminds you of stop.

stop

stop closes the session, releases the sampler demand, and writes one JSON artifact to reports/ that embeds the health snapshot, the closed session and the platform. The command then prints the path:

Profiler session stopped after 42s, 41 samples — report written to
reports/meowmc-report-20260101-120000.json (web upload is off: no endpoint)
Example output.

The parenthetical is the truth today: web upload is off. See Report artifacts.

Two reports in the same second never overwrite each other

The artifact path is stamped to the second, and a unique-name pass appends -2, -3, and so on while a report already occupies the name.

status

status answers the running session — scope, duration, samples taken, threads held — or, when nothing is running, the last session. It also lists the session history: the last eight closed sessions, held in memory only; the report artifact remains the pipeline answer.

Profiler session running (scope all), started 41s ago, 41 samples taken,
the session holds 28 threads.
Example output.

Rules worth knowing

  • Sampling is demand-driven. The sampler runs at 1 Hz while a session is open (or an /meow activity window, or a health read is demanded); between commands nothing samples.
  • stop is refused before the session is destroyed, not after. If the global configuration is not loaded, the session stays armed, the demand stays held, and stop can be re-run once the configuration is readable.
  • The first read after an idle gap is not a poisoned reading — the next demand re-baselines instead of dividing the window across the idle gap.