How to Detect a Defederation by Reading Sidekiq Queue Patterns

When a Mastodon instance defederates another instance, incoming activities from that instance stop arriving. But the effect on your own server can be subtle, especially if you are not actively monitoring federation logs. One reliable way to detect a defederation is by examining Sidekiq queue patterns. Sidekiq is the background job processor that Mastodon uses to handle incoming and outgoing activities. When an instance is defederated, the queues that process incoming federation messages from that instance will show a sudden drop or complete halt. This article explains how to read Sidekiq queue data in your Mastodon admin interface to identify a defederation event.

Why Sidekiq Queue Patterns Reveal Defederation

Mastodon uses Sidekiq to process federation activities asynchronously. When a remote instance sends an activity to your server, it enters a Sidekiq queue named pull (or a sub-queue like pull:default). The Sidekiq worker then processes that activity, such as delivering a new post to a local user’s timeline. If your instance defederates a remote instance, your server stops accepting incoming activities from that instance. The Sidekiq pull queue will no longer receive new jobs from that remote instance. Over time, the queue depth for that specific source will drop to zero and stay there. By contrast, queues for other remote instances will continue to show activity.

The key insight is that a defederation does not delete existing jobs in the queue. It only prevents new jobs from being enqueued from that source. So if you see a queue that was previously active become completely idle, and the last processed job timestamp is from the time of the defederation action, this is strong evidence of a defederation.

Understanding Sidekiq Queue Naming in Mastodon

Mastodon organizes Sidekiq queues by function. The relevant queues for detecting defederation are:

• pull — processes incoming federation activities (posts, likes, follows) from remote instances
• push — processes outgoing federation activities to remote instances
• default — general tasks, including some federation-related housekeeping

Each queue can have sub-queues named with a colon, such as pull:default. In a standard Mastodon deployment, you will see these queues listed in the Sidekiq admin interface at https://your-instance.example/sidekiq/queues.

Steps to Detect Defederation Using Sidekiq Queue Patterns

1. Access the Sidekiq Admin Interface
   Log in to your Mastodon server as an admin. Navigate to https://your-instance.example/sidekiq. If you have not set up a Sidekiq web UI route, you may need to access it via SSH and port forwarding. The default Sidekiq web interface runs on port 3000 on the local machine. Use ssh -L 3000:localhost:3000 user@your-server and then open http://localhost:3000 in your browser.
2. Check the Queues Tab
   Click the Queues tab at the top of the Sidekiq interface. You will see a list of all queues with their current depth (number of jobs waiting). Look for queues named pull or pull:default. Note the depth for each queue. If any pull queue shows a depth of zero and has not processed a job in the last few minutes, that indicates no incoming activities are being received from the corresponding remote instance.
3. Examine the Queue History
   Click on a specific queue name to see its history. Sidekiq shows a graph of processed jobs over time. Look for a sharp drop in processed jobs. If the drop coincides with the time you suspect a defederation was applied, that is a strong indicator. For example, if the graph shows a steady 50 jobs per minute before 14:00 UTC and then zero jobs after, the defederation likely happened at 14:00 UTC.
4. Compare with Other Queues
   To confirm the defederation is instance-specific, compare the pull queue behavior with push queues. A defederation blocks incoming traffic only. The push queue for that same instance might still show outgoing jobs if your users are posting content that tries to reach that instance. However, those outgoing jobs will likely fail and be retried. Look for a high number of retries in the push queue for that instance. This pattern — zero incoming, many outgoing retries — is a clear sign of a defederation.
5. Check the Failed Jobs Tab
   Sidekiq has a Retries tab that shows jobs that failed and are scheduled for retry. Filter by queue push and look for jobs destined for the suspected instance. The error message will often say HTTP 403 Forbidden or HTTP 410 Gone, which are standard responses from a defederating server.

Common Issues When Reading Sidekiq Queue Patterns

Queue Depth Shows Zero But No Defederation Occurred

A zero-depth queue does not always mean defederation. It can also mean that the remote instance is temporarily down or experiencing network issues. To differentiate, check the Busy tab in Sidekiq. If workers are actively processing jobs from that queue, the queue depth will fluctuate. If the queue has been zero for an extended period (more than 30 minutes) and no workers are busy on that queue, it is more likely a defederation.

Multiple Instances Defederated at Once

If you defederated multiple instances in a batch, you will see multiple pull queues drop to zero simultaneously. In that case, the Sidekiq interface will show a cluster of zero-depth queues. This pattern is easier to spot because it affects several queues at once.

Sidekiq Queue Names Differ Across Mastodon Versions

Older versions of Mastodon used different queue naming conventions. For example, version 3.x used pull and push as above. Version 4.x introduced sub-queues like pull:default. If you are on a very old version (pre-3.0), you may see queues like incoming and outgoing. Adjust your search accordingly. Check your Mastodon version in the admin panel under Administration > About.

Item	Normal Activity	After Defederation
Pull queue depth	Fluctuates between 1 and 100+	Stays at zero for hours
Pull queue processed jobs	Steady rate of 10–100 per minute	Drops to zero and remains flat
Push queue retries	Occasional failures (0–5%)	High retry rate (50%+) with 403 errors
Worker activity on pull queue	Multiple workers busy	No workers assigned to that queue

Reading Sidekiq queue patterns gives you a reliable method to detect a defederation without relying on external monitoring tools. By regularly checking the pull queue depth and comparing it with push queue retries, you can spot defederation events quickly. For ongoing monitoring, consider setting up a simple script that checks the Sidekiq API at /sidekiq/api/queues and sends an alert if a pull queue drops to zero for more than 10 minutes. This proactive approach helps you maintain awareness of your instance’s federation status.