You are browsing a read-only backup copy of Wikitech. The live site can be found at

Memcached for MediaWiki: Difference between revisions

From Wikitech-static
Jump to navigation Jump to search
imported>Wolfgang Kandek
Line 92: Line 92:
380K dump.txt
380K dump.txt
</syntaxhighlight>In this case the key's value is pretty big, and it needs PHP to be interpreted correctly (to unserialize it), but nonetheless we got some useful information (like the size of the key). This could be useful when it is necessary to quickly get how big a key is, rather than knowing its content.
</syntaxhighlight>In this case the key's value is pretty big, and it needs PHP to be interpreted correctly (to unserialize it), but nonetheless we got some useful information (like the size of the key). This could be useful when it is necessary to quickly get how big a key is, rather than knowing its content.
== Runbooks ==
* [[Memcached for MediaWiki/Memcached server failure|Memcached server failure]]

== See also ==
== See also ==

Revision as of 06:41, 11 March 2021

This page is about Memcached for MediaWiki.

This page is not about other Memcached clusters in production, such as those for Thumbor, Wikimedia Cloud Services, Wikitech wiki, and Swift.

Wikipedia's Memcached configuration as of November 2020. Detailing the use of additional "onhost" Memcached instances, local to MW web servers (handled via Mcrouter route prefixes).


There are two logical pools of Memcached servers for MediaWiki:

  • Main: The main pool for has 18 shards and runs on the mc10XX hosts (in Eqiad) and mc20XX hosts (in Codfw).
  • Gutter: The gutter pool has 3 shards and runs on the mc-gp100x and mc-gp200x hosts, which have 10Gbit/s NICs instead of 1Gbit/s.

See #Mcrouter for how these are used.

Magic numbers

  • WANCache (last updated: May 2020.)
    • Tombstone (aka "hold-off TTL"): 11 seconds.
    • Interim value: 1 second.
  • Mcrouter


WANObjectCache is the abstraction layer in MediaWiki PHP that deals with multi-datacenter concerns and Mcrouter. It builds on top of BagOStuff which is the generic key-value class that abstracts the Memcached protocol itself.

See also:

High level

  • Like a replica. There is generally no proactive setting of values during HTTP write actions. Instead, values are computed based on information from replica DBs, and computed on-demand using the getWithSet(key, ttl, callable) idiom. This means the application generally only expects cache values to be as up to date as a replica DB would be. Historically, it was common for MediaWiki to populate its cache during HTTP write actions instead. This meant that in a single-DC setup it could loosely be expected that the cache was as up-to-date as the master DB. As part of the multi-dc effort, this was changed starting in 2015, and thus its expectations were loosened to that of a replica DB.
  • No synchronisation. MediaWiki's WANObjectCache layer does not require synchronisation of cached values across data centers. Instead, it considers each datacenter's Memcached cluster as independent. Each populating its own values as-needed on dc-local app servers from dc-local replica DBs.
  • Tombstones (broadcasted purge). During HTTP write actions, MediaWiki asks WANObjectCache to purge cache keys of which it has modified the source data. These purges take the form of short-lived Memcached keys known as "tombstones". We do not use the DELETE command because we want each data center to be able to populate its memcached independently, thus requiring no cross-dc master database connection, thus reading from a local replica, thus values ingested in the cache may be as stale as a replica can be. Implementing a Memcached purge as DELETE would mean both in the same DC and other DCs, the same key could be re-populated immediately with the same stale value we just deleted. Instead, WANObjectCache formulates its purge as a SET operation that stores a placeholder value known as a "tombstone" (lasts for approx. 10 seconds for local and remote replica DBs to catch up).
  • Interim values. Upon seeing such tombstone, WANObjectCache acts much like a cache miss, except that the newly computed value is not written back over the tombstone (as the computed value may be stale). Instead, to avoid a recompute stampede these maybe-stale values are stored as an "interim value" in a sister key which is only kept for a few seconds.

Memcached commands


  • Read traffic from the getWithSet idiom results in a GETS command (getMulti) that fetches the main key, plus any sister keys that might exist.
  • Write trafffic from the getWithSet idiom results in either ADD if the key was known to be absent, or Memcached->mergeViaCas if a value existed but either required (or was elected for) regeneration.


  • Purge traffic uses the /*/mw-wan/ prefix to tell Mcouter to broadcast this to other pools and clusters as well. The actual command is generally SET as it needs to induce a "hold-off" period using the tombstone (per the above). In rare cases where a hold-off is not needed (e.g. if the purge is not related to a DB write), then the broadcasted event will use DELETE

Getting revision/page from WANObjectCache key

If you're trying to track down the specific revision text given an SqlBlobStore key, the somewhat convoluted procedure is documented at mw:Manual:Caching#Revision_text.


Main article: Memcached for MediaWiki/mcrouter


There is a local Mcrouter instance on every app server.

There is also a cluster of 4-shard "Proxies" pool of Mcrouter instances in each data center for the purpose of receiving cross-dc Memcached commands to then proxy further to the dc-local app servers accordingly.

TODO: Do these proxies also consider their dc-local gutterpool?


Each MediaWiki api/appserver sees memcached through a local proxy called Mcrouter[1]. Each route applies consistent hashing on the key name to know where to send it.

There are several routes available through this, which are addressable via a route prefix that Mcrouter strips from the key before forwarding the Memcached command.

  1. Main route. This route is declared as /$region/mw/ but is not addressed by MediaWiki as such. It routes to the dc-local "Main" pool shards. If a shard is perceived as unavailable from an appserver ("TKO") the local Mcrouter forwards all commands (incl gets, sets, and locks) to a shard of the "Gutter" pool instead (see T240684, T244852).
    • This route is used by the majority of traffic, through WANObjectCache::getWithSet calls in MediaWiki.
    • MediaWiki doesn't use the /$region/mw/ prefix. Instead /$region/mw/ is the default route and MediaWiki sends these commands without any routing prefix.
    • Switchover to and from the gutterpool is decided by Mcrouter locally (per-appserver), it is not centrally coordinated. The keys stored in a gutter server have a reduced TTL.
  2. WAN route. This route is declared as /$region/mw-wan/. It routes to the dc-local "Main" pool shards as well as the "Proxies" for all non-local DCs.
    • This route is for internal use by MediaWiki's WANObjectCache to broadcast its purges ("tombstones"). This happens from calls to WANObjectCache::purge (invalidates a single key) or WANObjectCache::touchCheckKey (effectively invalidate many keys, through a shared "check" key; somewhat like the Varnish XKey mechanism).
    • This route is not used for storing "regular" values is not exposed to any generic WANObjectCache::getWithSet or BagOStuff calls.


The Memcached key WANCache:v:metawiki:translate-groups (belongs to the Translate extension) is formatted by the WANObjectCache library. When Translate wants to get the value of this key, WANObjectCache will send a GET command from MediaWiki to localhost:11213, where Mcrouter is listening. The command is then further routed to mc1022 (based on key hashing). MediaWiki it totally ignorant about the mc[1,2]0XX host, it only knows about sending commands to a localhost port. A Mcrouter admin command helps figure out where keys are hashed/routed to:

elukey@mw1345:~$ echo "get __mcrouter__.route(get,WANCache:v:metawiki:translate-groups)" | nc localhost 11213 -q 2
VALUE __mcrouter__.route(get,WANCache:v:metawiki:translate-groups) 0 16

elukey@mw1345:~$ dig -x +short

Some things to notice:

  • The special prefix __mcrouter__.route is intercepted by Mcrouter. These are admin commands, for which proxy returns directly without contacting the Memcached hosts. This function returns the target of the consistent hashing of the key name.
  • Mcrouter listens on port 11213 on all MediaWiki app servers, meanwhile on every mc10XX host memcached listens on port 11211.

To get a key and dump it to a file it is sufficient to:

elukey@mw1345:~$ echo "get WANCache:v:metawiki:translate-groups" | nc localhost 11213 -q 2 > dump.txt
elukey@mw1345:~$ du -hs dump.txt
380K	dump.txt

In this case the key's value is pretty big, and it needs PHP to be interpreted correctly (to unserialize it), but nonetheless we got some useful information (like the size of the key). This could be useful when it is necessary to quickly get how big a key is, rather than knowing its content.


See also