ServersPulse

Configuration

Plugin configuration

The agent reads a YAML file named config.yml from its data folder. This file is created automatically on first startup.

Full config reference

# ServerPulse Agent Configuration
api-key: ""
backend-url: "https://api.serverspulse.com"
interval-seconds: 30
debug: false

api-key

The permanent API key used for authenticated ingest requests.

  • Blank by default
  • Filled automatically when you run /serverspulse register <code>
  • If blank or missing, the agent will not start sending data

Never share your API key publicly. If compromised, delete the server entry in the dashboard and create a new one with a fresh registration code.

backend-url

The backend endpoint the plugin sends data to.

  • Default: https://api.serverspulse.com
  • Leave this as-is unless you are running a self-hosted backend
  • The registration command also uses this value when redeeming codes

interval-seconds

How often the agent collects and sends a performance snapshot (in seconds).

  • Default: 30
  • Minimum allowed: 5

Lower values give you more granular data but generate more network traffic. Keep this aligned with your plan limits:

PlanMinimum interval
Free30 seconds
Starter10 seconds
Pro10 seconds
Multi5 seconds

Setting an interval below your plan's minimum will still work at the plugin level, but the backend enforces rate limits based on your plan.

debug

When set to true, the plugin emits additional diagnostic logs including:

  • Agent capability information at startup
  • Snapshot send details and response codes
  • Update check results
  • Retry and transport debug messages

Only enable this while troubleshooting. Disable it during normal operation to keep logs clean.

Applying changes

Changes to config.yml are not applied automatically. You must either:

  • Run /serverspulse reload (no restart required)
  • Restart the Minecraft server

Successful registration via /serverspulse register <code> writes the API key and triggers a reload automatically.

Validation rules

The plugin validates the config on load and will log errors for:

RuleRequirement
api-keyMust not be blank
backend-urlMust not be blank
interval-secondsMust be >= 5

If validation fails, the agent logs the error and will not attempt to send data until the config is corrected and reloaded.

Dashboard server settings

In addition to the plugin config, each server has settings you can manage from the dashboard:

Server name

A human-readable name shown in the sidebar, alerts, and reports. Change this from the server's Settings tab.

Server group

An optional label for organizing multiple servers (e.g., "Survival", "Minigames", "Hub"). Servers with the same group are visually grouped in the server list.

Server deletion

Permanently removes the server entry, all historical metrics, incidents, player data, and notification rules. This action cannot be undone. Only the server owner can delete a server.

Operational tips

  • Use registration codes for normal setup so operators do not need to hand-edit API keys
  • Keep backend-url on the default endpoint unless you know you need a custom backend
  • Turn on debug only while diagnosing issues -- disable it afterward
  • Use /serverspulse status to confirm the active interval, backend URL, and connection state after changes
  • If switching plans, update interval-seconds to match your new plan's allowance

Contributors

Thanks to everyone who keeps this docs area accurate.

bwmpbwmp