How to Audit Mastodon Federation Logs for Spam Inflow Patterns

Mastodon instance administrators often notice a sudden increase in spam or unwanted content appearing in the federated timeline. This traffic typically originates from specific remote servers that bypass local content filters. Mastodon records every incoming federation action in a structured log file, but most admins do not examine this data for spam patterns. This article explains how to locate, read, and analyze Mastodon federation logs to identify spam sources and block them before they affect your users.

Why Spam Inflow Patterns Appear in Federation Logs

Mastodon uses ActivityPub protocol to exchange messages between instances. When a remote user posts content, their instance sends an HTTP POST request to your instance. Your Sidekiq worker processes this request and stores the content in your database. Federation logs record every step of this process, including the sender domain, the activity type, and the HTTP status code returned.

Spam servers send a high volume of requests in a short period, often with identical or near-identical content. They may also send malformed JSON payloads that cause processing errors. By auditing the logs, you can detect three common spam patterns: repeated 422 Unprocessable Entity errors from the same domain, a sudden spike in Create activities from a single server, and a high ratio of failed deliveries to successful ones.

Log File Locations and Formats

Mastodon writes federation logs to several locations depending on your deployment method. For Docker-based instances, logs are stored inside the container and can be accessed with docker logs mastodon-web. For systemd-based installations, use journalctl to view Sidekiq logs. Standard file-based logs are located in /var/log/mastodon/ with names like production.log and sidekiq.log. Each log entry contains a timestamp, process ID, severity level, and a structured message that includes the ActivityPub activity type and the actor domain.

Steps to Audit Federation Logs for Spam Patterns

The following steps assume you have SSH access to your Mastodon server and can run commands as a user with sudo privileges. If you use a managed Mastodon hosting service, you may need to request raw log access from your provider.

1. Open a terminal session to your Mastodon server
   Use SSH to connect to the server that runs your Mastodon instance. For example: ssh admin@your-server-ip. If you use Docker, first attach to the mastodon-web container: docker exec -it mastodon-web bash.
2. View real-time federation logs with journalctl
   Run sudo journalctl -u mastodon-sidekiq -f --since "24 hours ago". This command shows live log output from the Sidekiq service. Press Ctrl+C to stop the output. For file-based logs, run tail -f /var/log/mastodon/sidekiq.log instead.
3. Filter log entries for ActivityPub processing workers
   In a separate terminal window, run sudo journalctl -u mastodon-sidekiq --since "24 hours ago" | grep "ActivityPub::ProcessingWorker". This isolates entries that show your instance processing incoming activities. Each line includes the actor domain, activity type, and status.
4. Identify domains with high error rates
   Run sudo journalctl -u mastodon-sidekiq --since "24 hours ago" | grep -E "422|500|503" | awk '{print $NF}' | sort | uniq -c | sort -nr. This command counts how many HTTP error responses your server returned, grouped by domain. A domain with more than 50 errors in 24 hours is likely a spam source.
5. Check for duplicate content patterns
   Run sudo journalctl -u mastodon-sidekiq --since "24 hours ago" | grep "Create" | grep -oP 'actor\":\"[^"]+' | cut -d'"' -f2 | sort | uniq -c | sort -nr | head -20. This lists the top 20 domains that sent Create activities. If one domain appears hundreds of times, examine its content manually.
6. Block the spam domain from the admin dashboard
   Log into your Mastodon instance as an admin. Go to Preferences > Administration > Moderation > Federation. Enter the offending domain in the search box. Click the domain name, then select Block domain. Confirm the action. This prevents all future activities from that domain.
7. Create a script to automate pattern detection
   Save the following script as /usr/local/bin/spam-audit.sh and make it executable with chmod +x /usr/local/bin/spam-audit.sh. Run it daily via cron to receive email alerts.

#!/bin/bash
LOG_ENTRIES=$(sudo journalctl -u mastodon-sidekiq --since "24 hours ago" | grep "ActivityPub::ProcessingWorker" | wc -l)
ERROR_COUNT=$(sudo journalctl -u mastodon-sidekiq --since "24 hours ago" | grep -E "422|500|503" | wc -l)
TOP_DOMAIN=$(sudo journalctl -u mastodon-sidekiq --since "24 hours ago" | grep "Create" | grep -oP 'actor\":\"[^"]+' | cut -d'"' -f2 | sort | uniq -c | sort -nr | head -1)
echo "Total federation events: $LOG_ENTRIES"
echo "Total error responses: $ERROR_COUNT"
echo "Top spam domain candidate: $TOP_DOMAIN"

Common Issues When Auditing Federation Logs

No Logs Appear After Running journalctl

If journalctl returns no output, verify that the mastodon-sidekiq service is running: sudo systemctl status mastodon-sidekiq. If the service is inactive, start it with sudo systemctl start mastodon-sidekiq. For Docker users, ensure the container is running: docker ps | grep mastodon-web.

Log Contains Many 422 Errors From Legitimate Servers

A 422 Unprocessable Entity error can occur when a remote instance sends a valid ActivityPub payload that your instance rejects due to a local rule, such as a content warning requirement. Check the error message in the log entry. If the message says “Record invalid” or contains a validation error, the remote server is likely not spam. Only block domains that show a pattern of repeated identical errors with no valid content.

Spam Domains Change Frequently

Spam operators rotate domains to evade blocks. Instead of blocking each domain manually, use the Moderation > Federation > Allow list feature to restrict federation to a curated set of trusted instances. This is a drastic measure that reduces discoverability but eliminates spam entirely. Alternatively, use the MASTODON_FEDERATION_ALLOWLIST environment variable to enforce an allowlist at the application level.

Mastodon Federation Log Audit Methods Comparison

Item	journalctl (systemd)	File-based logs	Docker logs
Command	journalctl -u mastodon-sidekiq -f	tail -f /var/log/mastodon/sidekiq.log	docker logs mastodon-web –tail 50
Real-time output	Yes	Yes	Yes
Historical search	Yes, with –since flag	Yes, with grep	No, must pipe to file
Disk space usage	Low (systemd journal)	High (uncompressed text)	Medium (Docker JSON files)
Best for	systemd-based deployments	Traditional Linux servers	Docker Compose setups

After you identify and block spam domains using the federation log audit process, your instance will serve cleaner content to users. Run the audit script weekly to catch new spam sources early. For advanced protection, combine domain blocking with the Preferences > Administration > Moderation > Reports feature to let users flag suspicious accounts directly.