Mastodon Monitoring with Vigilmon: Web UI, API Health, Sidekiq & Federation Checks

Your Mastodon instance was up — the homepage loaded, users could log in, and posts appeared to go through. But for six hours, nothing was federating. Incoming boosts and replies from other instances piled up in the Sidekiq queue unprocessed. Your users' posts weren't appearing on other servers. The queue had grown to 40,000 jobs and Sidekiq had silently stopped processing them.

Mastodon is a self-hosted federated microblogging platform built on the ActivityPub protocol. Running a healthy Mastodon instance means keeping the Rails web process, the Sidekiq background job queue, the PostgreSQL database, Redis, and the Nginx proxy all healthy simultaneously. When any layer fails, the failure mode is often invisible to users until it's very wrong. Vigilmon gives you the external monitoring to catch these failures early.

This tutorial walks through monitoring Mastodon end-to-end with Vigilmon.

What You'll Build

• A Vigilmon HTTP monitor on the Mastodon web UI
• An API health check using Mastodon's /api/v1/instance endpoint
• A Vigilmon heartbeat monitor for Sidekiq background job health
• A federation endpoint check
• SSL certificate expiry alerts

Prerequisites

• A running Mastodon instance (v4.x recommended)
• A free account at vigilmon.online

Step 1: Monitor the Mastodon Web UI

The Mastodon homepage is the entry point for all users. A healthy homepage confirms that Nginx, the Puma Rails server, and the database connection pool are all working.

Test it:

curl -I https://mastodon.yourdomain.com/

You should see 200 OK with a Content-Type: text/html response. Mastodon's landing page renders instance information from the database, so a 200 here implies database connectivity.

Set up the Vigilmon monitor:

1. Log in to Vigilmon and click New Monitor → HTTP.
2. Set URL to https://mastodon.yourdomain.com/.
3. Set Check interval to 60 seconds.
4. Set Expected status code to 200.
5. Under Advanced → Keyword check, add keyword present: mastodon.
6. Save the monitor.

Step 2: Monitor the Instance API Endpoint

Mastodon's /api/v1/instance endpoint returns instance metadata — title, description, version, active user stats, and contact email. It's the canonical health endpoint used by clients, bots, and federation discovery. A non-200 response here almost always means the Rails process is unhealthy or the database is unreachable.

Test it:

curl https://mastodon.yourdomain.com/api/v1/instance

Healthy response (truncated):

{
  "uri": "mastodon.yourdomain.com",
  "title": "My Mastodon",
  "version": "4.2.8",
  "stats": {
    "user_count": 42,
    "status_count": 1500,
    "domain_count": 800
  }
}

Set up the API monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to https://mastodon.yourdomain.com/api/v1/instance.
3. Set Expected status code to 200.
4. Under Advanced → Keyword check, add:
   • Keyword present: "version"
   • Keyword absent: "error"
5. Save.

This endpoint requires no authentication and is safe to check from external monitors.

Step 3: Sidekiq Background Job Health via Heartbeat

Sidekiq processes ActivityPub deliveries, email notifications, media processing, and federation. When Sidekiq stops processing — due to Redis connectivity loss, a crashed worker process, or memory exhaustion — your instance appears healthy from the outside but is silently broken.

Mastodon's Sidekiq scheduler can be configured to send a regular heartbeat ping to Vigilmon. Set this up with a cron-based Sidekiq job:

Step 3a: Create the Vigilmon heartbeat monitor.

1. Click New Monitor → Heartbeat in Vigilmon.
2. Set Name to Mastodon Sidekiq Scheduler.
3. Set Expected interval to 5 minutes.
4. Set Grace period to 2 minutes.
5. Save and copy the unique heartbeat ping URL (e.g., https://vigilmon.online/heartbeat/abc123).

Step 3b: Add a Sidekiq cron job to ping Vigilmon.

In your Mastodon Rails app, create config/schedule.yml (if using sidekiq-cron) or add to your existing schedule:

vigilmon_heartbeat:
  cron: "*/5 * * * *"
  class: "VigilmonHeartbeatJob"
  queue: scheduler

Create the job at app/jobs/vigilmon_heartbeat_job.rb:

class VigilmonHeartbeatJob < ApplicationJob
  queue_as :scheduler

  def perform
    uri = URI("https://vigilmon.online/heartbeat/abc123")
    Net::HTTP.get(uri)
  rescue StandardError => e
    Rails.logger.error "Vigilmon heartbeat failed: #{e.message}"
  end
end

Now Sidekiq pings Vigilmon every 5 minutes. If the ping stops arriving, Vigilmon alerts you — indicating Sidekiq has stopped processing or Redis is unreachable.

Step 4: Monitor the Federation Endpoint

Mastodon's ActivityPub federation relies on the .well-known/webfinger endpoint. Other instances use this to look up your users and deliver posts. If it goes down, your users become unreachable on the fediverse even though your instance looks healthy locally.

Test it:

curl "https://mastodon.yourdomain.com/.well-known/webfinger?resource=acct:admin@mastodon.yourdomain.com"

Healthy response:

{
  "subject": "acct:admin@mastodon.yourdomain.com",
  "links": [...]
}

Set up the monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to https://mastodon.yourdomain.com/.well-known/webfinger?resource=acct:admin@mastodon.yourdomain.com.
3. Set Expected status code to 200.
4. Under Advanced → Keyword check, add keyword present: subject.
5. Save.

Replace admin with a real account on your instance.

Step 5: SSL Certificate Monitoring

ActivityPub federation uses HTTPS exclusively — other instances will refuse to deliver to your server if your certificate is expired or invalid. Vigilmon automatically monitors SSL certificate validity on all HTTPS monitors.

1. Open your Mastodon web UI monitor in Vigilmon.
2. Under Advanced → SSL, ensure Alert before expiry is enabled (default: 14 days).
3. Save.

Step 6: Alert Channels

Go to Notifications → New Channel in Vigilmon and configure:

• Email — for your instance admin
• Webhook — for Slack, Discord, or Matrix (many Mastodon admins run Matrix)

A Sidekiq heartbeat alert looks like:

🔴 DOWN: Mastodon Sidekiq Scheduler (Heartbeat)
No ping received in the last 7 minutes (expected every 5)
Triggered: 2026-03-01 08:14 UTC

What You've Built

| Scenario | How Vigilmon catches it | |---|---| | Rails/Puma process crash | HTTP monitor detects 502 from Nginx | | Database connection failure | /api/v1/instance returns non-200 | | Sidekiq stopped processing | Heartbeat monitor misses scheduled ping | | WebFinger / federation broken | .well-known/webfinger monitor fails | | SSL certificate expired | HTTPS monitor reports TLS error | | Redis unavailable | Sidekiq heartbeat stops arriving | | DNS misconfiguration | HTTP monitor detects resolution failure |

Running a Mastodon instance for your community is a real responsibility — users trust you with their social presence on the fediverse. Vigilmon's layered monitoring ensures you know about infrastructure problems before your users discover them via missing notifications or broken federation.

Start monitoring your Mastodon instance today — register free at vigilmon.online.