Skip to content
Essentials
The plugins Docs Sign in

Essentials Monitoring

Open Essentials Monitoring Last changed November 9, 2026

Essentials Monitoring tells you what your Pelican panel is doing and what is about to go wrong. Its watchdog checks your nodes, disks, memory, queue worker, versions and (if you want) backups and schedules on a timer, and sends a message to Discord, email, your own bot or the panel's notification bell when something changes. Around that it adds read-only overview pages for administrators (system status, capacity, backups, schedules, panel activity, incident history with node uptime), a block on the admin dashboard, a warning for server owners whose backups are behind, and an optional public status page that anybody can open without an account.

At a glance

Plugin ID essentials-monitoring
Current version 1.4.2
Pelican Panel 1.0 (tested on 1.0.0-rc.2)
Needs The scheduler (the watchdog timer, the status page rebuild and the "scheduler is alive" mark). The queue worker (the watchdog's checks run on it). The frontend build, for its stylesheet (Node.js and Yarn on the panel server). The panel's mailer only for email alerts; a Discord webhook or a bot address of your own only if you use those channels.
Works with (optional) Essentials Core (the Parts window, the module list on the dashboard block, the module alert), Essentials Appearance (status page styles), Essentials Game Manager (player counts on the status page), Essentials Shop (shop alerts), Essentials Arranger (a Service status element), Essentials Mobile (bell alerts as a push message)
Adds Admin area, sidebar group Essentials Monitoring: System status (/admin/system-status), Alerts (/admin/essentials-alerts), Incidents (/admin/essentials-incidents), Backups (/admin/essentials-backups), Status page (/admin/essentials-status), Activity (/admin/essentials-activity), Schedules (/admin/essentials-schedules), Capacity (/admin/essentials-capacity). A block on the admin dashboard. For server owners: Needs attention and (if allowed) Status page in the account menu, and a warning above their server list. Public: /status and /status/<name>. One database table, essentials_monitoring_incidents.
Permissions Role editor section Essentials Monitoring: view and update for everything, plus a pair per part: alerts/view-alerts, status/view-status, system/view-system, backups/view-backups, capacity/view-capacity, activity/view-activity, schedules/view-schedules, machines/view-machines (see "First-time setup")

Before you install

  • No old legacy plugin running. If the legacy all-in-one "Essentials" (plugin id essentials) is enabled and too old to hand monitoring over, this module refuses to start and Pelican shows "Update legacy Essentials to a version supporting standalone Monitoring, or disable legacy Essentials before enabling this plugin. No settings have been changed." In any case, do not run the all-in-one beside any essentials-* module (see "Things to watch out for").

  • Node.js and Yarn on the panel server. This module ships a stylesheet, which Pelican compiles into the panel's own frontend build when the plugin is installed. The build must run as the panel's web user.

  • A queue worker that runs. Pelican's background worker, usually the systemd service pelican-queue. The watchdog's checks are handed to it, and installs from the admin area run there too. Check it with systemctl status pelican-queue.

  • The scheduler (a cron job that runs Pelican's timed tasks every minute). The entry for the web user is:

    * * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1
    

    Add it with sudo crontab -e -u www-data. The examples on this page assume Pelican is in /var/www/pelican and the web server user is www-data (Debian/Ubuntu). On another setup, adapt the path and the user (for example nginx on some systems).

  • For the channels you want to use: a Discord webhook (made in Discord under Server Settings -> Integrations -> Webhooks -> New Webhook -> Copy Webhook URL), the panel's mailer set up under Admin -> Settings -> Mail (send Pelican's own test mail first), or an https address of your own that receives a signed JSON post. The panel must be allowed to make outgoing https requests for Discord and the bot.

  • Pelican Panel 1.0. Pelican 1.0.0-rc.2 itself needs PHP 8.4 or 8.5.

  • Essentials Core is optional, but recommended here. With Core installed this module appears in Core's module list on the Essentials page, with its health notes and its switches in the Parts window, which is the only place in the panel where most of its parts can be switched off and on. Without Core it works on its own with every part on.

Installing

Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Monitoring and a version, and download the zip. x.y.z is a stable release, x.y.z-beta a test release and x.y.z-dev a development build. Use stable on a live panel.

Then install it one of these ways. The first is the easiest.

  1. From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. The plugin appears in the list; press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)

  2. From the Essentials website. Connect your panel on the website with a Pelican application key. You make that key on the panel under Admin -> API keys, with read and write on Plugins; it starts with papp_. Then press Install on the plugin's page on the website.

  3. With the Essentials Auto Updater. If that plugin is installed, its Plugin updates page offers Essentials modules that are not installed yet.

  4. From the command line (advanced).

    cd /var/www/pelican
    sudo unzip essentials-monitoring-x.y.z.zip -d plugins/
    sudo chown -R www-data:www-data plugins/essentials-monitoring
    sudo -u www-data php artisan p:plugin:install essentials-monitoring
    sudo -u www-data php artisan p:plugin:list
    

    The folder must be exactly plugins/essentials-monitoring. The list must show the plugin as enabled. Unzipping over an existing plugin folder resets it to "not installed" (its status is kept in its own plugin.json), so always run the install command again after unzipping.

What the install does:

  • It runs one migration, which creates the table essentials_monitoring_incidents (the incident history).
  • Every part is switched on, including the watchdog: it checks every 15 minutes and sends to the panel's notification bell. Its very first run only learns the current state and sends nothing.
  • Tell people their server is offline is switched on too (see "Things to watch out for").
  • On a panel that ran the all-in-one before: settings this module has never saved are read from the values the all-in-one wrote into .env (the LEGEND_THEME_... lines), so alerts and the status page carry on as they were until you save them here. Permissions granted under the all-in-one's shared role editor section are copied to the Essentials Monitoring section once.

After every install:

  • If pages look unstyled or buttons are missing, the frontend build did not run: cd /var/www/pelican && sudo -u www-data yarn build. With Essentials Core, the Panel health section on the Essentials page reports missing built assets.
  • The plugin clears Pelican's route and view caches and asks the queue worker to restart. If a new page answers 404 or an old version still shows, reload PHP-FPM (sudo systemctl reload php8.4-fpm, use your PHP version) and restart the worker (sudo systemctl restart pelican-queue).
  • Run artisan, yarn and file commands as the web user (sudo -u www-data ...), never as root. Files created by root cause errors and failed updates later.

First-time setup

  1. Give your staff roles the permissions: Admin -> Roles, open a role, section Essentials Monitoring. view lets somebody look at every part, update lets them change every part (and gives them this module's Parts window on Core's page). Or grant per part: the plain name (for example alerts) lets them change that part, the view- name (shown as, for example, View Alerts) only lets them look. alerts covers Alerts and Incidents, status the Status page, system System status, machines the machines on the dashboard block, and backups, capacity, activity and schedules their own pages. Root Admins have everything already.
  2. Check the worker test. The dashboard block, and from 1.4.1 on every scheduled watchdog run, sends a small test job; the dashboard reports "No queue worker answered..." if nothing picks it up. On 1.4.0, open the admin dashboard once so the watchdog can know whether the worker is there.
  3. Set up the watchdog: sidebar group Essentials Monitoring, page Alerts.
    1. How often: Check every (Off - no checks at all, 5 minutes, 15 minutes (the default), 30 minutes, Hour, or Day, which runs at 09:00). Each check asks every node's daemon once. Remind me while it lasts: hours between reminders while a problem lasts; 0 (the default) means no reminders.
    2. Channels. Use more than one; they fail differently.
      • Discord, with the Webhook address (https only).
      • In the panel: a notification in the bell for everybody holding view, alerts or view-alerts. On by default.
      • Email: one or more addresses, comma separated. Filling it in switches email on; leave it empty to switch it off. It uses the panel's own mailer.
      • A bot of your own, with Where to post it (https only) and a Signing secret. Nothing is sent while the secret is empty. See "Things to watch out for" for what the bot receives.
    3. What to watch: Warn when a node's disk is over and Warn when a node's memory is over (90 % by default, 0 switches the check off), Warn about maintenance left on for (hours, 0 is off, the default), Panel and Wings versions, Queue worker and Tell me when a queued job fails (all three on by default). Off by default: Backups falling behind (with Call a backup stale after, 7 days), Scheduled tasks that have stopped, the shop checks Paid and not built, Packages running out (with Warn when this many are left) and Ports running out (these need Essentials Shop), and A module that is on and not working (needs Essentials Core).
    4. Press Save at the top of the page, then Send a test. The test is sent straight away, not through the queue, and the list Where messages go shows per channel Delivered, Refused (with the reason and what to do), Nothing sent yet or Off. Each row has its own Test button.
  4. Decide about owner alerts. Tell people their server is offline sends every owner of a server on a node that stops answering a notification in their bell, and another when it comes back. Switch it off in the Parts window if you do not want that (see "Things to watch out for").
  5. The public status page (optional): page Status page. Nothing is public until you add something:
    1. What is published: Publish a server, pick the Server and type how it is Shown as. Type a public name rather than the internal one.
    2. Machines: Publish a machine shows a node as up or down, nothing more. Type a public name for it too.
    3. Other services: Add a service with a Name, an https Address and optionally Expect (a status code; leave empty for "any answer").
    4. Pages for your users: Let users make their own lets server owners publish a page of their own at /status/<name>, showing only servers they own. They find it under Status page in their account menu.
    5. Wording: Heading, Link to the panel, Check every (from 10 seconds to 60 minutes; 1 minute by default), Style and A line above the list.
    6. Press Save. Open the page appears once something is published; the address is /status on your panel.
  6. System status: page System status shows the machine the panel runs on (processor, memory, swap, each disk, load average, uptime, operating system, PHP, panel version) and any nodes you add. Options has Show the machines on the dashboard, Read again every, Show (which cards) and Nodes to show. A version card that is behind links to the release notes; updating the panel and Wings is done on the machines themselves.

The other pages need no setup and change nothing on the panel:

  • Backups: every server you can reach with Last backup, Kept, Size and Failed, never-backed-up servers first. A backup counts as stale after the Call a backup stale after days set on Alerts.
  • Capacity: per node, what has been promised (memory, disk, processor, including Pelican's overallocation) against what it may hand out, and servers that are at a limit for backups, databases or allocations. Promised, not used.
  • Activity: every event in Pelican's activity log across the panel, newest first, with filters. IP addresses only show for people with Pelican's own permission to see them. How long lines are kept is Pelican's setting under Settings -> Misc.
  • Schedules: every scheduled task, worst first: Stuck (processing for over 6 hours), Overdue (its next run is more than an hour past), Never run, No tasks, Fine, Off. Editing a schedule stays on the server's own page.
  • Incidents: every problem the watchdog raised, when it started, how long it lasted and whether it is still Ongoing, with each node's Uptime over 7 days and 30 days. Maintenance does not count against uptime.
  • For server owners: Needs attention in the account menu lists their own servers that have never been backed up, have a stale backup or a stopped scheduled task, and a line above their server list says the same when something is behind.

Things to watch out for

  • Subusers see only what their permissions allow. On a server they share, a subuser sees its backup status only with Pelican's backup read permission and its schedules only with the schedule read permission (from 1.4.2 on). Owners and admins see everything they saw before.
  • Owner alerts are on after installing. Tell people their server is offline is on from the start (the description in 1.4.0 wrongly said it starts off). When a node stops answering, the owners of its servers (up to 200 people per check, never subusers) get a notification in the bell, and another when it is back. Switch it off in the Parts window if your customers should not get these.
  • Without Essentials Core, parts can only be switched off in the settings file. Most parts have no switch on their own pages. Without Core, add their names to features_off in storage/app/private/essentials/monitoring/settings.json, for example "features_off": ["owner_alerts"]. The names are backups, capacity, activity, schedules, system_status, my_backups, owner_alerts, alerts, public_status and dashboard_nodes. Edit it as the web user (sudo -u www-data nano ...) and keep the file valid JSON; if it does not exist yet, create it with only that line inside { }.
  • Switching a part off removes its pages. Alerts off also removes Incidents and stops the watchdog. Public status page off makes /status answer 404.
  • The System status page's "Show in the sidebar" switch. Switching it off takes the page out of the sidebar; its address keeps working and its Options window keeps the switch (from 1.4.1 on). On 1.4.0 the Options button disappeared instead; use the Parts window (System status page) there.
  • The watchdog and the queue worker. Scheduled checks are handed to the worker. When the worker test goes unanswered, the scheduled checks run without it, so a dead worker is still reported. From 1.4.1 on the watchdog sends that test itself; on 1.4.0 only the dashboard did, so a dead worker could keep the checks waiting in the queue on a panel where nobody opened the dashboard. Run the checks now always goes through the queue. Send a test does not.
  • The watchdog is quiet on purpose. It sends a message when something changes and when it recovers, not on every check. A check that cannot read anything has to fail twice in a row before it counts. The first run after installing, and the first run after Forget what it knows, learn the current state and send nothing, so a problem that is already going on is reported one run later. A node in maintenance is skipped by every other check.
  • Webhook addresses and the signing secret are credentials. They are stored encrypted with the panel's APP_KEY and never shown again in the form ("Saved. Leave empty to keep it, or type a new one to replace it."). If you change the APP_KEY, enter them again. Only https addresses are accepted.
  • Email fails silently when the mailer is not set up. Use Send a test after any change to Admin -> Settings -> Mail. With Core, a health note says when the mailer only writes to its log.
  • What the bot receives. One JSON post per message with panel, title, body, good, at, event (for example node.reachable), kind (raised, reminder or cleared), class and subject. The header X-Essentials-Signature carries sha256= and the HMAC-SHA256 of the body made with your signing secret; your bot should refuse anything that does not match. Also tell the bot when something happens adds event notices that are not faults (shop.paid, shop.built, shop.failed, service.due, service.suspended, ticket.said); each is off until ticked and goes to the bot only.
  • The public status page is public. It shows the names you type, whether each is up and, with Essentials Game Manager, how many players are on. Do not publish internal names. Other services makes the panel fetch the addresses you enter on a timer, so give the status permission only to people you trust with that. User pages publish servers their owners choose, under names they type.
  • Two pages called Backups. This module's Backups page is at /admin/essentials-backups. The Automatic backups page of Essentials Backups used the same address in its first release (0.0.1), so only one of the two could be opened; from Essentials Backups 0.0.2 on it has its own address.
  • Do not save a role while this plugin is disabled. The role editor only keeps the permissions of plugins that are running, so saving a role while Essentials Monitoring is switched off removes its permissions from that role.
  • The legacy all-in-one plugin. "Essentials" (plugin id essentials) is the older plugin that contains what the modules now do separately. Never run it on the same panel as any essentials-* module: installing a module switches the all-in-one off, installing the all-in-one on a panel with modules can switch modules off, and uninstalling the all-in-one deletes database tables the modules share (shop, tickets, API keys). Pick one: the all-in-one, or the modules.

Things to keep an eye on

  • Where messages go on the Alerts page. A channel that says Refused delivers nothing while the panel looks fine. Press Test on that row after fixing it.
  • The dashboard block. It warns "No queue worker answered..." when the worker test goes unanswered, and "The panel's scheduler has not run for ... minutes" when the scheduler has been silent for over ten minutes. Below that it shows this panel and every node with CPU, memory, disk and load, and with Essentials Core the list of Essentials modules.
  • Health notes. With Essentials Core, the module's row on the Essentials page says when alerts are on but the interval is Off, when every channel is off, when Discord has no valid https webhook, when the bot is missing its https address or secret, when email has no valid address or the mailer only writes to its log, when owner alerts are on but the watchdog is not running, and when the public status page is on with nothing published.
  • The queue worker. Recommended: Restart=always on the pelican-queue service, and a drop-in with StartLimitIntervalSec=0 under [Unit] (sudo systemctl edit pelican-queue) so systemd never gives up restarting it after repeated crashes. If it has given up, sudo systemctl reset-failed pelican-queue && sudo systemctl start pelican-queue brings it back.
  • Incidents. A quick way to see what the watchdog found and how reliable each node has been. Resolved incidents are kept for 180 days.
  • Logs. Every message the watchdog sends is written to storage/logs/laravel-YYYY-MM-DD.log (or laravel.log) as "Essentials watchdog: ...", and a failed run as "Essentials watchdog: the run failed - ...". That is the record to check when somebody says they did not receive an alert. Pelican's log viewer reads the whole file, so very large logs (around 100 MB) make it fail; Essentials Core warns above 50 MB.

When alerts are too noisy:

  • Keep Remind me while it lasts at 0, or set a long interval.
  • Raise the disk and memory thresholds, or set one to 0 to switch it off. Put nodes you are working on in maintenance; they are not checked while they are.
  • Backups falling behind counts every server without a recent successful backup, except servers with a backup limit of 0 (from 1.4.1 on; 1.4.0 counted those too). Set Call a backup stale after to match how often you really back up, or leave this check off.
  • Tell me when a queued job fails reports new failed jobs since the last check. Fix the cause and clear the failed jobs (sudo -u www-data php artisan queue:retry all puts them back once the cause is fixed).
  • After removing a node the watchdog keeps reporting, press Forget what it knows.
  • A longer Check every means fewer checks and fewer requests to your nodes.

When alerts stay silent:

  • Check that Check every is not Off and that Alerts is switched on in the Parts window.
  • Press Send a test and read Where messages go.
  • Check the queue worker (systemctl status pelican-queue) and open the admin dashboard so the worker test runs. Check the scheduler.
  • Remember the first run after installing or after Forget what it knows sends nothing.
  • In the panel only reaches people holding view, alerts or view-alerts (and Root Admins). "Nobody holds the permission" in the list means nobody qualifies.
  • Look for "Essentials watchdog" lines in the log.

Updating

Download the new version and import it the same way you installed it (Pelican shows Update on the plugin when an update is known), or let the Essentials Auto Updater do it. The module switches itself back on after an update through the admin area. Settings, channel credentials and the incident history are kept; credentials still stored unencrypted from an older version are encrypted on update. Make a database backup before updating, since the incident history lives in a table. If pages look unstyled afterwards, run sudo -u www-data yarn build in /var/www/pelican.

Removing it

Uninstall it under Admin -> Plugins, or from the command line:

cd /var/www/pelican
sudo -u www-data php artisan p:plugin:uninstall essentials-monitoring --delete

--delete also removes the plugin's files. Uninstalling stops the watchdog and the status page rebuilds, removes every page and the dashboard block, makes /status and every user's status page answer 404, and drops the table essentials_monitoring_incidents, so the incident history and uptime are lost. Notifications already sent stay in people's notification lists.

Files stay behind in storage/app/private/:

  • essentials/monitoring/: the settings and a few small marker files.
  • legend-theme/alerts/: what each check said last and what each channel did last.
  • legend-theme/status/: the service list and the users' status pages.

Delete them by hand if you do not plan to reinstall. Delete only these two subfolders of legend-theme, never the whole folder: other Essentials modules keep their own files in it.

sudo rm -r /var/www/pelican/storage/app/private/essentials/monitoring
sudo rm -r /var/www/pelican/storage/app/private/legend-theme/alerts
sudo rm -r /var/www/pelican/storage/app/private/legend-theme/status

Any LEGEND_THEME_... lines the all-in-one wrote into .env are only read by this module, never changed or removed.

Troubleshooting

Problem What to do
The plugin shows an error: "Update legacy Essentials to a version supporting standalone Monitoring, or disable legacy Essentials..." Disable the legacy all-in-one "Essentials" plugin (or update it), then enable this module again.
Pages look unstyled or buttons are missing Run cd /var/www/pelican && sudo -u www-data yarn build.
No alerts arrive at all Work through "When alerts stay silent" above.
"No queue worker answered" on the dashboard Start or restart the worker: sudo systemctl restart pelican-queue (and reset-failed first if systemd gave up).
"The panel's scheduler has not run for ... minutes" Check the cron entry for schedule:run (sudo crontab -l -u www-data).
Discord is Refused with 401 or 404 The webhook was deleted, regenerated or pasted incompletely. Make a new one in Discord and paste the whole URL.
Email is Refused with 550 or 553 Your mail server refuses the panel's From address. Fix it under Admin -> Settings -> Mail; Pelican's own test mail there fails the same way.
In the panel is Refused: "nobody holds the permission" Give a role view, alerts or view-alerts in Essentials Monitoring.
The webhook or signing secret seems to be gone The panel's APP_KEY changed. Enter them again and save.
The watchdog keeps reporting a node you removed Press Forget what it knows on Alerts.
Customers ask about "One of your servers is offline" notifications That is Tell people their server is offline. Switch it off in the Parts window if you do not want it.
/status answers 404 Check that Public status page is on and that at least one server, machine or service is published and saved. If it still answers 404, clear the caches: sudo -u www-data php artisan optimize:clear.
A server shows Unknown on the status page The panel could not reach that server's node (often maintenance or a daemon restart). It does not mean the server is off.
The Options button on System status is gone On 1.4.0 this happens when Show in the sidebar was switched off: switch System status page back on in the Parts window, or update to 1.4.1.
The Automatic backups entry of Essentials Backups opens this module's Backups page Essentials Backups 0.0.1 used this module's address. Update Essentials Backups to 0.0.2 or later.
Saving shows "Could not save" or "Nothing was saved" The panel cannot write to its storage folder. Make sure storage/app belongs to the web user (sudo chown -R www-data:www-data /var/www/pelican/storage). The reason is in the log.
A new page answers 404 after installing or updating Reload PHP-FPM (sudo systemctl reload php8.4-fpm) and restart the queue worker.

Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.

Put Essentials on your home screen

Your browser can install it now. It opens in a window of its own, without the address bar, like any other app.