Amaryn Pulse

## What it does

Amaryn Pulse sends performance metrics from your Minecraft server to the
**Amaryn Pulse** iPhone app. Check TPS, MSPT, memory and players from your
phone, get a push notification the moment something breaks, and see exactly
at which player count your server starts to lag.

Status apps can only ping your server. Pulse runs inside it.

**Sampled every 30 seconds:**
- Players online and average ping
- TPS (1m/5m/15m), average and 95th-percentile MSPT
- Heap usage, GC pauses, process CPU
- Loaded chunks and entity counts per world
- Free disk space, uptime, restarts and crashes
- A count of ERROR log lines (never their contents)
- Server software, Minecraft version, plugin count
## Data and privacy, please read

**This plugin sends data to a remote server.** Metrics go to Amaryn's
backend at `pulse.amaryn.app`. That is required for the plugin to work.

**It never sends:**
- Player UUIDs, in any field
- Chat, commands, coordinates, inventories or IP addresses
- Log contents (error lines are counted, never read)
- Your worlds, configs or any other file
**Live player list (opt-out):** with `send_player_list: true` (the default)
the names of players currently online are sent so the app can show a live
roster. The backend keeps them in memory for about 90 seconds and never
writes them to disk. Set it to `false` and the app shows a count only.

**Watchlists are matched on your server.** If you ask the app to tell you when
a certain player joins, the plugin does the matching locally and only reports
back the label you chose.

Full privacy policy: https://amaryn.app/privacy

## Why use it

- **Real metrics:** TPS, MSPT and memory, which ping-based apps can't see
- **Alerts:** offline, TPS or MSPT too high, heap too full, player thresholds,
all with your own limits
- **Insights:** 30-day uptime, peak hours, and the player count where your
tick rate starts to drop
- **Incident history:** restarts, crashes and error spikes measured against
your server's own baseline
- **Widgets and Live Activities** on your iPhone
- **Proxy networks:** add only your Velocity proxy and pick the backends from
a checklist
- **Player groups:** sort the live player list by rank using any permission
plugin (Pro)
## Lightweight

- Sampling and all network calls run on their own thread, never the main
thread (only the per-world chunk/entity count takes a few hundred
microseconds there; drop `worlds` from `enabled_metrics` to remove it)
- Bounded queue and exponential backoff during outages
- Any unexpected error stops Pulse, never your server
- About 140 KB, no runtime dependencies
## Setup

1. Drop the jar in `plugins/` and restart. It registers itself.
2. Run `/pulse follow` in game to get a six-character code.
3. Enter the code in the Amaryn Pulse app within ten minutes. Done.
**Running a network?** Put the same jar on the Velocity proxy and on every
backend, then add only the proxy in the app. On Velocity the command is
`/vpulse` instead of `/pulse`.

Keep follow codes private: anyone with a valid code can follow your server.

## Compatibility

One jar for **Spigot, Paper, Purpur and Folia 1.20.4+** and **Velocity 3.4+**.
Requires Java 21.

- Folia reports the laggiest region's TPS and MSPT; chunk and entity counts
are not available on Folia yet
- On Spigot, MSPT is read from server internals and left empty if unavailable
- Velocity has no TPS or MSPT; the app shows a network view instead
## Commands

On Spigot/Paper/Purpur/Folia use `/pulse`, on Velocity use `/vpulse`.

| Command | Permission | Description |
|---|---|---|
| `status` | `pulse.follow` or `pulse.admin` | What the plugin is doing, works unlinked |
| `follow` | `pulse.follow` | Create a code to add this server to the app |
| `rename <name>` | `pulse.admin` | Change the name shown in the app |
| `network` | `pulse.admin` | `/vpulse` only: backends and their status |
| `reload` | `pulse.admin` | Reload `config.yml` |
| `unlink confirm` | `pulse.admin` | Revoke this server's token and remove all followers |

Both permissions default to op.

## App

The Amaryn Pulse app for iPhone is free to download. The free plan includes
unlimited ping-only servers and one plugin-connected server with 24 hours of
history. Pro and Network add more servers, longer history, more alert rules
and player groups. See https://amaryn.app for details.

Not an official Minecraft product. Not approved by or associated with Mojang
or Microsoft.