pumpkin-pulse

pumpkin-pulse provides performance monitoring and recordings for Pumpkin servers. It is inspired by spark, with the measurements built around Pumpkin's own tick and plugin APIs.

pulse 1.0 covers live server health, player latency, slow tick alerts and recording sessions. It does not sample Rust call stacks or allocations yet; Pumpkin's WASM plugin API does not currently expose the host access needed to do that properly.

What it records

A recording can include:

• tick durations
• incoming and outgoing packet counts
• outgoing packet sizes and packet types
• chunk loads, saves and sends
• player joins and leaves
• entity counts for each world

Packet recording is disabled by default. Pumpkin's packet-sent event copies the packet payload into the plugin, so it is best enabled only for short captures when it is needed.

Commands

Command	Description
/pulse start	Start a recording with the default channels
/pulse start <channels> [--timeout <seconds>]	Record selected channels, optionally stopping after a set time
/pulse stop	Stop the recording and write its report
/pulse status	Show the current recording and how long it has been running
/pulse tps	Show TPS and tick statistics over 10-second, 1-minute and 5-minute windows
/pulse health	Show TPS, MSPT, players, entities, host memory and system information
/pulse ping [player]	Show the server's ping distribution or one player's ping
/pulse tickmonitor [milliseconds|off]	Toggle slow tick alerts or set their threshold
/pulse bar enable <metrics>	Show live tps, mspt, ping, and/or host ram boss bars
/pulse bar disable	Remove the performance bars

Channels passed to /pulse start are comma-separated. For example:

/pulse start ticks,chunks,packets
/pulse start ticks,chunks --timeout 60

Only one recording can run at a time. /pulse tps also works when no recording is active. Running /pulse tickmonitor starts the monitor at 50ms. Run it again, or pass off, to stop it.

Bar metrics are comma-separated and update once per second:

/pulse bar enable tps,mspt,ping,ram

CPU usage is not available to WASM plugins in the current Pumpkin API, so pulse does not display a made-up CPU value. It can be added once the host exposes that measurement.

Output

Recordings are written to:

plugins/data/pulse/session-<unix timestamp>/

The directory contains one CSV file for each enabled channel and a report.txt summary. The report includes tick percentiles, the five slowest ticks, packet and chunk totals and rates, and the player join and leave counts collected during the session.

Building

rustup target add wasm32-wasip2
cargo build --release --target wasm32-wasip2

Copy target/wasm32-wasip2/release/pumpkin_pulse.wasm into the server's plugins directory.

Permissions

pulse needs fs.write.data to write recordings and sys.info for the host section of /pulse health. You can approve them when the server asks, or add them to pumpkin.toml:

[plugins]
allow_unsigned = true
allowed_permissions = ["fs.write.data", "sys.info"]

The /pulse command uses the pulse:command permission. It is available to operators at permission level 2 or above by default.