feed-health: per-feed monitoring for WordPress importers

A WordPress plugin that tracks yield, failures, HTTP status and duplicate rate for every feed an importer fetches, and alerts when a feed goes quiet, starts failing, stops being fetched or recovers.

feed-health is a WordPress plugin for the operator of a site that imports from feeds. It records each fetch attempt and what it yielded, shows every feed on one admin screen, and emails or logs when a feed goes quiet, starts failing, stops being fetched or recovers. The code is at https://github.com/IndianOpinion/feed-health, licensed MIT. Version v0.1.0 was released on 15 November 2026.

We wrote it from scratch from an idea, not from any third-party plugin. It has not run on a live site. The 47 utilities in this series were specified, built, reviewed and released between 11 and 19 November 2026 by language-model coding agents under the editor’s direction, in five roles: a spec writer, a spec reviewer, a builder that saw only the spec, an independent code reviewer and a releaser. The editor made the rulings on every open question.

The problem

A site that imports from many feeds has no view of the feeds themselves. One feed can stop returning items, start answering with an error page, move address, or keep returning articles that other feeds already supplied. The site looks fine. The loss shows up weeks later as a thin section or a missing source.

The PRD names three things that make this worse:

  • Import runs are scheduled jobs, and their log output is often discarded.
  • One fatal error inside a run can stop every feed after it. From outside, the feeds just go quiet.
  • Output is bursty. A quiet hour is normal for most feeds, so someone who looks now and then cannot tell a slow feed from a dead one.

What it does

  • Stores every fetch attempt with an outcome: ok, not_modified, http_error, transport_error, parse_error, empty, cached or failure_other. A parse_error is a 200 that is not a feed, such as a bot challenge, a login wall or a parked domain.
  • Reduces every item to a key and decides whether it is fresh, a repeat or a duplicate.
  • Gives each feed one status, with a reason built from the numbers: paused, failing, unchecked, quiet, redundant, degraded, new or healthy.
  • Adapts the “quiet” threshold to each feed’s own cadence.
  • Shows a Tools page and a dashboard widget, with a wp feed-health command set (status, check, test-alert, events, mute, snooze, prune).
  • Sends batched alerts by email, by log, or both, and recovery notices.

How it works

Feeds are identified by an adapter key and a feed key, never by position or URL. An importer reports in one of three ways: by swapping fetch_feed() for a wrapper, through plain-array WordPress actions, or by implementing an Adapter class. A passive mode observes every core fetch_feed() call through the wp_feed_options and http_api_debug hooks, with no code change.

do_action( 'feed_health_fetch', [
    'adapter' => 'my-importer', 'feed_key' => 'world', 'feed_url' => $url,
    'outcome' => 'ok', 'http_status' => 200, 'items' => 20, 'run_id' => $run_id,
] );

A Recorder buffers fetches and items, then flushes at the end of a run, at 500 rows, and on shutdown. An item key is a hash of the canonical URL: no scheme, no www., m., mobile. or amp. label, no fragment, no trailing slash, no tracking parameters, sorted query. Item bodies are never stored.

A Checker runs hourly, after each import run and daily. It reads only the plugin’s own tables and never fetches. Its status rules are pure functions, so each is tested with plain numbers. The quiet threshold is twice the 90th percentile gap between new-item arrivals over 14 days, clamped between 6 hours and 7 days. Below five recorded gaps a default of 48 hours applies.

The notifier follows changes, not states. It applies a cooldown per feed and status, reminders, flapping detection (more than four status changes in 24 hours), a daily email cap, and one systemic alert when most feeds fail together, which usually points at the site’s own network.

Guard rails

  • Nothing breaks an import. Every recording call catches its errors, counts them and logs once per request. With the kill switch off, recording returns before touching the database.
  • It never fetches feeds on its own schedule. The only fetch it makes is the operator’s “test fetch now”, through core, limited to once per feed per five minutes.
  • The default daily email cap is 10 per site. On multisite a network cap can also be set. Held notices are logged and counted in the next email.
  • URLs are redacted (user info and secret-looking query values) before they reach the dashboard, email, logs, CLI output or CSV.
  • CSV cells beginning with =, +, - or @ get a leading quote, so a hostile feed label cannot become a spreadsheet formula.
  • The plugin stores no reader data. It keeps feed URLs, one-way hashes of article URLs, the newest title per feed, and the user ids of staff who act on the dashboard.
  • Admin actions check a nonce and a capability, and destructive ones need a POST and a confirmation.

What review changed

The independent code review found and fixed these before the merge:

  • Fetches larger than the flush cap were stored wrong. Later chunks added the item count again, so a 520-item fetch was stored as 541. The newest date and newest title came from the last chunk only, which for a newest-first feed holds the oldest items. Totals are now carried across chunks, and a retry never inserts a second row for one fetch.
  • While the daily cap held mail, every check rebuilt the same reminder and added it to the held-back count again. A held reminder now waits one reminder period.
  • Settings could not be saved under a filtered capability. The save now follows feed_health_capability.

The review also raised static analysis from level 6 to level 8.

Limits and what is next

  • Seen keys are kept 30 days after an item was last seen. A feed that relists an older item counts it as fresh again.
  • Duplicates are the same article URL after canonicalisation. Near duplicates are not detected.
  • Core caches feeds for 12 hours by default. Cached calls are recorded as cached and are not attempts.
  • Passive mode counts items but cannot tell which the site imports, so it computes no yield or duplicates.
  • There is no public suffix list, so the cross-host redirect warning can be wrong for rare suffixes.
  • On the roadmap: a weekday and hour profile for feeds with strong daily cycles, REST endpoints for the dashboard data, and chunked prunes. A large prune currently runs as one DELETE per table.
  • One open issue: an admin notice prints the fh_notice URL parameter after escaping it, so a crafted link can show misleading text that looks like a plugin message. The proposed fix is a keyed message table that ignores unknown values.

Test status: this is v0.1.0. There are 155 PHPUnit tests, mostly on stubs and mocks with a frozen clock, plus 3 integration tests against a throwaway MySQL 8.0. Static analysis and code style checks passed. The GitHub CI workflow has not run: the commit adding it stayed local because the token lacked the workflow scope.

Install

It needs WordPress 6.4 or later, PHP 8.1 or later, and MySQL 5.7+ or MariaDB 10.4+. It has no runtime dependencies.

composer require indianopinion/feed-health

The package is not on Packagist yet, so add a Composer vcs repository entry for https://github.com/IndianOpinion/feed-health first.

Or copy the folder to wp-content/plugins/ and activate it. A must-use loader is in examples/.

All 47 utilities · feed-health on GitHub

Search Trending
Loading

Signing-in 3 seconds...

Signing-up 3 seconds...

All fields are required.