Monitoring Misskey with Vigilmon

Misskey is an open-source, ActivityPub-compatible decentralized microblogging platform built with Node.js and TypeScript. It stands out in the Fediverse for its emoji reactions, custom icons, drive file management, and highly customizable theming — and has spawned popular forks including Calckey/Firefish, Iceshrimp, and Sharkey. Your Misskey instance federates with Mastodon, Pleroma, Pixelfed, and every other ActivityPub server on the network, which means background federation queues are critical to keeping your community connected. Vigilmon gives you uptime monitoring for the Misskey web UI, API health checks, job queue status alerts, and SSL certificate expiry notifications — so you know before your users do when something goes wrong.

What You'll Set Up

• HTTP uptime monitor for the Misskey web UI
• API availability check for the /api/meta instance metadata endpoint
• Job queue health alert via /api/admin/queue/stats
• SSL certificate expiry alerts for your Misskey domain
• Heartbeat monitoring for Misskey background cleanup and federation jobs

Prerequisites

• Misskey (or a fork: Firefish, Iceshrimp, Sharkey) running on port 3000 or behind a reverse proxy
• Admin credentials if you want to monitor the authenticated queue stats endpoint
• A free Vigilmon account

Step 1: Monitor the Misskey Web UI

The Misskey web application serves its frontend from the root path. Add a basic HTTP availability check so you know immediately if the Node.js process crashes or the reverse proxy stops responding.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Misskey URL: https://misskey.yourdomain.com (or http://yourserver:3000 if not behind a proxy).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If you want a lighter check that avoids serving the full SPA bundle, you can target the index directly:

https://misskey.yourdomain.com/index.html

Both paths return a 200 when Misskey is healthy and serving traffic.

Step 2: Monitor the /api/meta Instance Metadata Endpoint

Misskey exposes a REST API at /api/meta that returns JSON instance metadata including the software version, instance name, and active user counts. A successful response here confirms the Node.js application is up and the API layer is functional — a deeper check than just verifying the web UI loads.

The endpoint accepts a POST request with an empty JSON body:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Enter URL: https://misskey.yourdomain.com/api/meta
3. Set Method to POST.
4. Set Request body to {}.
5. Set Request header Content-Type to application/json.
6. Set Expected HTTP status to 200.
7. Set Expected response body contains to "version" (the field is always present in a valid response).
8. Click Save.

A failure here while the web UI is up usually indicates a database connectivity issue or a crashed API worker — the kind of partial failure that's easy to miss without dedicated API monitoring.

Step 3: Monitor the Job Queue via /api/admin/queue/stats

Misskey uses a Redis-backed job queue (Bull/BullMQ) to handle federation, media processing, note cleanup, and scheduled maintenance. A stalled queue can cause federation to stop working for hours before users notice. The /api/admin/queue/stats endpoint returns queue depths and worker counts for all Misskey job types.

This endpoint requires authentication. First, create a Misskey admin API token:

1. Log in to your Misskey instance as an admin.
2. Go to Settings → API → Generate access token.
3. Grant the token read:admin scope.
4. Copy the token.

Then add the monitor in Vigilmon:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter URL: https://misskey.yourdomain.com/api/admin/queue/stats
3. Set Method to POST.
4. Set Request body to {"i": "YOUR_ADMIN_TOKEN"}.
5. Set Request header Content-Type to application/json.
6. Set Expected HTTP status to 200.
7. Set Expected response body contains to "deliver" (the federation delivery queue key).
8. Click Save.

If the endpoint returns a non-200 or the response body is missing expected queue keys, Vigilmon will alert you. You can also use Vigilmon's keyword alert to trigger on specific conditions — for example, alert if the body contains "waiting": followed by a large number indicating a backlogged federation queue.

Step 4: SSL Certificate Alerts

Misskey instances should always run over HTTPS — plain HTTP exposes ActivityPub federation tokens and user sessions. Let's Encrypt certificates renew automatically via Certbot or Caddy, but renewal failures are silent until the certificate actually expires.

1. Open the HTTP / HTTPS monitor created in Step 1.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

A 21-day window gives you three renewal cycles of buffer. If your Misskey instance uses a wildcard certificate covering the main domain and federation subdomains, add a dedicated SSL monitor for each domain you want to protect.

Step 5: Heartbeat Monitoring for Background Jobs

Misskey runs background cleanup and maintenance tasks on a schedule: expired note cleanup, media garbage collection, and federation queue retry processing. If the Node.js process is alive but background jobs are stuck (common after Redis restarts or OOM kills of worker threads), your instance looks healthy from the outside but federation slowly degrades.

Use Vigilmon's cron heartbeat to verify that Misskey's background processing is actually completing:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 60 minutes (Misskey's typical cleanup cycle).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Then add a cron job on your Misskey server that pings the heartbeat URL only after successfully verifying the queue stats API returns a non-empty response:

# /etc/cron.d/misskey-heartbeat
# Run every 60 minutes — ping Vigilmon only if queue stats are reachable
*/60 * * * * misskey \
  curl -sf -X POST https://misskey.yourdomain.com/api/admin/queue/stats \
    -H 'Content-Type: application/json' \
    -d '{"i": "YOUR_ADMIN_TOKEN"}' | grep -q '"deliver"' \
  && curl -s https://vigilmon.online/heartbeat/abc123

If the queue stats endpoint is unreachable or the deliver key is missing, the && short-circuits and Vigilmon never receives the ping — triggering an alert after 60 minutes of silence.

Alternatively, instrument the heartbeat directly inside Misskey's built-in job system using a custom scheduled job if you have access to the Misskey source.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add your preferred channel: email, Slack, Discord webhook, or PagerDuty.
2. Set Consecutive failures before alert to 2 on the web UI monitor — Misskey Node.js startup after a PM2 restart takes 10–20 seconds and may cause a single probe miss.
3. Set Consecutive failures before alert to 1 on the queue stats monitor — a failed queue check is more likely a real problem than a transient hiccup.
4. Use Maintenance windows in Vigilmon during Misskey version upgrades, which require a brief restart and database migration.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://misskey.yourdomain.com/ | Node.js crash, nginx/Caddy down | | API meta | /api/meta (POST) | Database down, API worker crash | | Queue stats | /api/admin/queue/stats (POST) | Stalled federation queue, Redis failure | | SSL certificate | Misskey domain | Let's Encrypt renewal failure | | Cron heartbeat | Heartbeat URL | Background job system stall |

Misskey's rich features — emoji reactions, drive storage, federation with the entire ActivityPub network — all depend on background workers running reliably. With Vigilmon monitoring the web UI, API layer, job queues, and SSL certificates, you have full observability over every critical subsystem of your self-hosted Misskey instance.