LswMemcacheBundle
If you want to optimize your web application for high load and/or low load times Memcache is an indispensable tool. It will manage your session data without doing disk I/O on web or database servers. You can also run it as a central object storage for your website. In this role it is used for caching database queries using the Doctrine caching support or expensive API calls by implementing the caching using Memcache "get" and "set" commands.
This Symfony2 bundle will provide Memcache integration into Symfony2 and Doctrine for session storage and caching. It has full Web Debug Toolbar integration that allows you to analyze and debug the cache behavior and performance.
Read the LeaseWebLabs blog about LswMemcacheBundle
Requirements
- PHP 5.3.10 or higher
- php-memcached 1.0.2, 2.0.1 or 2.1.0 (this is the PHP "memcached" extension that uses "libmemcached")
NB: php-memcached 2.2.x gives runtime notices and should be avoided!
NB: Unlike the PHP "memcache" extension, the PHP "memcached" extension is not (yet) included in the PHP Windows binaries.
Installation
To install LswMemcacheBundle with Composer just add the following to your 'composer.json' file:
{
require: {
"leaseweb/memcache-bundle": "*",
...
}
}
The next thing you should do is install the bundle by executing the following command:
php composer.phar update leaseweb/memcache-bundle
Finally, add the bundle to the registerBundles function of the AppKernel class in the 'app/AppKernel.php' file:
public function registerBundles()
{
$bundles = array(
...
new Lsw\MemcacheBundle\LswMemcacheBundle(),
...
);
Configure the bundle by adding the following to app/config/config.yml':
lsw_memcache:
session:
client: default
clients:
default:
hosts:
- { dsn: localhost, port: 11211 }
Install the following dependencies (in Debian based systems using 'apt'):
apt-get install memcached php5-memcached
Do not forget to restart you web server after adding the Memcache module. Now the Memcache information should show up with a little double arrow (fast-forward) icon in your debug toolbar.
Usage
When you want to use the cache from the controller you can simply call:
$this->get('memcache.default')->set('someKey', 'someValue', $timeToLive);
$this->get('memcache.default')->get('someKey');
The above example shows how to store value 'someValue' under key 'someKey' for a maximum of $timeToLive seconds. In the second line the value is retrieved from Memcache. If the key can not be found or the specified number of seconds have passed the 'get' function returns the value 'false'.
Configuration
Below you can see a full configuration for this bundle.
lsw_memcache:
clients:
default:
persistent_id: default # Do NOT use this, see known issues
hosts:
- { dsn: 10.0.0.1, port: 11211, weight: 15 }
- { dsn: 10.0.0.2, port: 11211, weight: 30 }
options:
compression: true
serializer: json
prefix_key: ""
hash: default
distribution: consistent
libketama_compatible: true
buffer_writes: true
binary_protocol: true
no_block: true
tcp_nodelay: false
socket_send_size: 4096
socket_recv_size: 4096
connect_timeout: 1000
retry_timeout: 0
send_timeout: 0
recv_timeout: 0
poll_timeout: 1000
cache_lookups: false
server_failure_limit: 0
sessions:
hosts:
- { dsn: localhost, port: 11212 }
Session Support
This bundle also provides support for storing session data on Memcache servers. To enable session support
you will have to enable it through the session
key. Note that the only required subkey of
the session support is client
(a valid client). You can also specify a key prefix and an ttl.
lsw_memcache:
session:
client: sessions
prefix: "session_"
ttl: 7200
locking: true
spin_lock_wait: 150000
# clients
Note that the session locking is enabled by default and the default spin lock is set to poll every 150 milliseconds (150000 microseconds).
Doctrine Support
This bundle also provides support for Doctrine caching on Memcache servers. To enable Doctrine caching
you will have to enable it through the doctrine
key. Note that you can specify all three kinds of
Doctrine caching: 'metadata', 'result' and 'query'. The required keys within those subkeys are both
client
(a valid client) and entity_manager
(normally: default). You can also specify a prefix.
lsw_memcache:
doctrine:
metadata_cache:
client: default
entity_manager: default # the name of your entity_manager connection
document_manager: default # the name of your document_manager connection
result_cache:
client: default
entity_manager: [default, read] # you may specify multiple entity_managers
prefix: "result_" # you may specify a prefix for the entries
query_cache:
client: default
entity_manager: default
# clients
ADP: Anti Dog Pile
Let us examine a high traffic website case and see how Memcache behaves:
Your cache is stored for 90 minutes. It takes about 3 second to calculate the cache value and 1 ms second to read from cache the cache value. You have about 5000 requests per second and that the value is cached. You get 5000 requests per second taking about 5000 ms to read the values from cache. You might think that that is not possible since 5000 > 1000, but that depends on the number of worker processes on your web server Let's say it is about 100 workers (under high load) with 75 threads each. Your web requests take about 20 ms each. Whenever the cache invalidates (after 90 minutes), during 3 seconds, there will be 15000 requests getting a cache miss. All the threads getting a miss will start to calculate the cache value (because they don't know the other threads are doing the same). This means that during (almost) 3 seconds the server wont answer a single request, but the requests keep coming in. Since each worker has 75 threads (holding 100 x 75 connections), the amount of workers has to go up to be able to process them.
The heavy forking will cause extra CPU usage and the each worker will use extra RAM. This unexpected increase in RAM and CPU is called the 'dog pile' effect or 'stampeding herd' and is very unwelcome during peak hours on a web service.
There is a solution: we serve the old cache entries while calculating the new value and by using an atomic read and write operation we can make sure only one thread will receive a cache miss when the content is invalidated. The algorithm is implemented in AntiDogPileMemcache class in LswMemcacheBundle. It provides the getAdp() and setAdp() functions that can be used as replacements for the normal get and set.
Please note:
- ADP might not be needed if you have low amount of hits or when calculating the new value goes relatively fast.
- ADP might not be needed if you can break up the big calculation into smaller, maybe even with different timeouts for each part.
- ADP might get you older data than the invalidation that is specified. Especially when a thread/worker gets "false" for "get" request, but fails to "set" the new calculated value afterwards.
- ADP's "getAdp" and ADP "setAdp" are more expensive than the normal "get" and "set", slowing down all cache hits.
- ADP does not guarantee that the dog pile will not occur. Restarting Memcache, flushing data or not enough RAM will also get keys evicted and you will run into the problem anyway.
Considerations
LswMemcacheBundle uses the 'memcached' PHP extension (client) not the older 'memcache' PHP extension. For a comparison of the available clients see: http://code.google.com/p/memcached/wiki/PHPClientComparison
Known issues
The session write that invokes a memcache set operation is executed after the page has been rendered. The collect call of the memcache data collector is executed before the rendering of the page is complete and therefor also before the session write is executed. This causes the session writes not to show up in the Web Debug Toolbar.
Enabling persistent connections (setting "persistent_id") is known to crash php5 (core dump) on some systems. Use with caution: it is strongly recommended to leave out "persistent_id" from the configuration.
Credits
Doctrine support is based on the implementation in SncRedisBundle:
https://github.com/snc/SncRedisBundle by Henrik Westphal
- DependencyInjection/LswMemcacheExtension.php
- DependencyInjection/Configuration.php
- DependencyInjection/Compiler/EnableSessionSupport.php
Are based on implementation in:
https://github.com/Emagister/MemcachedBundle by Christian Soronellas
- Command/StatisticsCommand.php
Is based on an implementation in:
https://github.com/beryllium/CacheBundle by Kevin Boyd
License
This bundle is under the MIT license.
The "fast-forward" icon in the web debug toolbar is part of the Picas icon set (official website: http://www.picasicons.com). The icon is licensed and may only be used to identifying the LswMemcacheBundle in the Symfony2 web debug toolbar. All ownership and copyright of this icon remain the property of Rok Benedik.