Issue
How do I configure Acquia Purge? (This article applies to the Drupal 7 version of Acquia Purge)
Resolution
When you need to purge cache selectively, the Acquia Purge module is one of your best choices on Acquia Cloud. There are a number of steps you can take to optimize the usage of Acquia Purge and ensure that it is doing the job in the best way possible for your site.
Evaluating non-purged content
Every website is unique and there will be sections on your site that won't be caught by the Cache Expiration module's automatic detection. Ensuring the best usage for a given site requires a test and fine-tune phase before you bring this into production.
The Cache Expiration module detects ordinary changes (including creation, updates, or deletion) to content (such as nodes, comments, and user accounts). Whenever changes are made, the module provides the HTTP path for Acquia Purge to clear. In practice, however, the Cache expiration module can detect only about 90% of your website's content changes without additional configuration.
To evaluate the Cache Expiration module with your website, test your website as an anonymous user on either your Development or Staging environment. To do this anonymous user testing, you can use your browser's incognito browsing features (if available), or a different browser entirely, to look for changes that aren't detected by the Cache Expiration module. Make small page changes and then observe the behavior in the incognito browser window. For example, if you change the title of a content node, examine the pages that refer to that node to ensure that they display the updated title, including news sections and RSS feeds. Note any HTTP paths for pages that are having problems. The following are some examples that you might have:
news
news?page=1
products
products/toys
contact
about-us/team-overview
There are often common elements to pages that are not automatically purged. Pay close attention to any special caching that might be set up for Drupal, especially the following:
- Although the page is usually cleared by the Cache Expiration module, in some cases it may not be. Be sure to direct additional attention to it.
- The Views module allows you to aggregate content, either directly on paths (such as
/news
), in blocks, or in RSS feeds. Because the Cache Expiration module cannot easily detect where a changed piece of content is displayed in a view, views are not automatically purged. - Blocks can be placed on one or more pages on your site and show dynamic content (such as a view). Watch for blocks with dynamic content and note the pages on which they are rendered. One example is a "product of the day" block displayed on both the and
/products
. - The Contact page itself does not show any content from your site, but can contain blocks that use dynamic content.
- Pages generated by custom code or modules are less likely to be detected. Whenever your site actively exposes pages through Drupal's
hook_menu
system, include them in your tests.
Purging identified paths
After you have identified pages that aren't purged, you can configure Acquia Purge to handle them. To do this, you'll use the Rules module and the Clear pages on Acquia Cloud
rule action. You can then trigger the rule based on whatever condition you set. As a best practice, configure the rule to purge specific pages often instead of regenerating the cache for your entire site every few minutes.
Select from the following choices to handle the custom paths collected during testing:
- Purge all of the paths after every content change by using one rule. Although this is the simplest method, it can cause large amounts of unnecessary cache rebuilding.
- Create multiple rules that purge relevant paths. For example, a rule specifically for news nodes could clear all of the
/news*
paths. This requires more configuration up front, but is more efficient for your site over time. - Write custom code that calls the Acquia Purge API upon events. While this can provide very specific results, it can also require significantly more development effort. For more information, see the Acquia Purge FAQ.
Encouraging Varnish to serve your site
Drupal provides the Expiration of cached pages setting (page_cache_maximum_age
), which controls how long generated pages and other assets can be kept in a cache like Varnish. Usually this setting is on the low end, a habit especially seen on news websites. You can set this by going to Admin > Configuration > Performance and changing the Expiration of cached pages menu.
If this setting is low, your web servers and Drupal have to do more work and the load balancer is less effective. This is why proactive purging exists. With the expire and Acquia Purge modules tested and tuned, you can increase this value. Sites vary, but we suggest setting this value to a minimum of 6 hours
once you have identified an ideal configuration for purging your site and have completed successful testing of purging. The higher this value is set, the more efficient the process becomes.
Using Acquia Purge in production
After you've made your changes and finished testing in your development and staging environments, be sure to properly configure your production environment in an identical fashion and perform similar validation tests.
Regularly examine and test your website's cache clearing rules to ensure that they're working properly and that new pages are not failing to clear. If you see a specific page that needs to be cleared from the cache, you can use the administrative interface to do a spot clear of a cached page.
To perform a spot purge:
- Navigate to Configuration > Performance > Manual Purge.
- Under Paths to be purged, enter a path value in the text box.
- If there is more than one path to purge, click Add.
- When all of the paths are added, click Refresh.
There are also two blocks that can be made available on every page, for administrative purposes. These make it easy to purge a single path or page quickly:
- Manual purge form (current page)
- Manual purge form (paths)
Configuration variables
By strict design this module has no UI-exposed settings or configuration forms. The reason behind this philosophy is that, as a utility module, only site administrators should be able to change settings and these changes should be traceable in the settings.php
file. Although Acquia Purge is intended to be turnkey, with minimal configuration, the following options exist:
$conf setting | Default | Description with Code example |
---|---|---|
acquia_purge_allriskmode |
FALSE |
When set to TRUE, this disables full blocking checks for too high queue volumes and too many domain names. Using this mode excludes your support SLA entitlement and rules out support on these checks from the Acquia Purge issue queue.
|
acquia_purge_base_path |
(auto) |
In some cases Drupal isn't served on the same URL as where it's edited, which will cause more paths to be purged than necessary. By overriding this setting, Drupal's base_path() will no longer be used to construct purges. Use with caution.
|
acquia_purge_cron |
FALSE |
When set to TRUE , this will process queue items during cron. The client side AJAX processor cannot be disabled, but it will run less frequently, especially when late runtime processing is enabled.
|
acquia_purge_domains |
FALSE |
Allows you to control which domains will be purged. See Domains. |
acquia_purge_errorlimit |
TRUE |
The system shuts down when it counted too many HTTP errors. When TRUE , this limit is calculated with slowdown factor^3 , use drush apd to see the actual factor. If you want a static limit, this can be set as integer value.
|
acquia_purge_http |
TRUE |
Controls purging of http:// schemes, which is the default behavior. Disable this by setting it to FALSE , as long as you are purging https:// paths. If no schemes are being purged, the system will shut down and report an error.
|
acquia_purge_https |
FALSE |
EXPERIMENTAL https:// scheme support, disabled by default. If enabled, the total amount of work done will double. Monitor your system closely. Consider disabling http:// if your site is fully https:// based.
|
acquia_purge_lateruntime |
FALSE |
When enabled, processing of the queue will start during the same request items got added to it. Queues clear quicker and the role of the client-side AJAX processor reduces drastically. However, this does add RISK since pages can time/out or run out of memory! Test carefully!
|
acquia_purge_log_success |
TRUE |
By default, this module will log both successes and failures, which is helpful for those setting the module up. Once implementation is complete, set this to FALSE , which only logs failures and reduces queries or disk writes (for log files).
|
acquia_purge_memcache |
TRUE |
Determines whether Acquia Purge needs to store its state data in memory when $conf['cache_default_class'] is set to use it. This reduces I/O activity compared to the fallback file-based state storage and also improves deduplication of queue items. If you are seeing issues with queuing and purging items, consider disabling it followed by drush ap-forget .
|
acquia_purge_passivemode |
FALSE |
When set to TRUE, this causes hook_expire_cache() to stop working and effectively allows the module to remain enabled in local environments without actually purging automatically.
|
acquia_purge_silentmode |
FALSE |
TRUE hides the client-side AJAX processor regardless of what the purge on-screen permission is set to. It is not possible to disable the processor, but its role is highly reduced in combination with cron mode and late runtime processing.
|
acquia_purge_smartqueue |
FALSE |
When set to TRUE, the smart queue backend will be loaded instead. It automatically disregards items that Varnish has already dropped and this backend can be a big efficiency improvement on sites with TTLs not set to weeks or months. WARNING: if your site dynamically sets the page_cache_maximum_age variable or max-age Cache-Control header value, using this setting will make purging VERY UNRELIABLE!
|
acquia_purge_token |
FALSE |
Allows you to set a custom X-Acquia-Purge header value. This helps offset DDOS-style attacks but requires balancer level configuration changes. You need to contact Acquia Support.
|
acquia_purge_variations |
TRUE |
If enabled, this aids administrators using drush ap-purge or the manual purge form because it will purge common variations of the paths to be purged. For instance, versions with ?page parameters and paths with trailing slashes are made up for every manually purged path, but you can disable this behavior by setting this to FALSE .
|
acquia_purge_sphpskippath |
TRUE |
By default, the sites.php domain detection skips records that to not end on a known TLD, and assumes the remainder is a path. Disable this to enable experimental support for all of sites.php .
|
acquia_purge_stripports |
80,443 |
Strips ports from records in sites.php that start with a first octet that is numeric, such as 443.domain.com . Ports outside this setting are not stripped from detected domains.
|
Drush commands for Acquia Purge
These are the current Acquia Purge commands available using drush. Several of these commands have been presented in use cases previously.
ap-diagnosis
- Perform a series of diagnostic self-testsap-domains
- List all domains Acquia Purge will purge againstap-forget
- Forget all scheduled purges and empty the queueap-list
- List all the items that are in the queueap-process
- Purge all queued items from the command lineap-purge
- Purge a specified path from your balancers
Module questions and comments
If you have any questions or comments about the module for its maintainer, or you've found a bug or some other issue, you can file an issue in the Acquia Purge issue queue .