Professional Documents
Culture Documents
Contents
1. Introduction ......................................................................................... 4 2. About Aptimize Accelerator ................................................................. 4
Installation ............................................................................................................................................. 4 Configuration ........................................................................................................................................ 6
4. Identifying speed bottlenecks .............................................................. 9 5. Key concepts for working with WAX.................................................. 10
Using WAX query string commands ................................................................................................... 10
The wax.config file Custom rules and settings WAX resource naming Transforming content
11 11 12 13
Example 1: Padding on combined images is missing ........................................................................ 13 Example 2: Bootstrapper script loads its own dependencies ............................................................. 13 Example 3 : Versioning URLs of other objects ................................................................................... 14 Transformation Tips ............................................................................................................................ 15
JavaScript debugging Tracing HTTP traffic flow Logging and debug trace Reading waterfall charts Rule 1: Reduce the time it takes for the server to respond to a request Rule 2: Reduce the number of objects being loaded by HTML pages
15 15 16 17 18 19
Page 1 of 56
Rule 3: Reduce the size of everything sent from the server Rule 4: Cache everything as much as possible to speed up repeat views
24 25
Public proxy caching ........................................................................................................................... 25 In memory caching ............................................................................................................................. 26 Disk caching ....................................................................................................................................... 26
26
Instructing WAX to process content from other sites ......................................................................... 26 Leveraging a Content Delivery Network ............................................................................................. 28
8. Deployment to Production................................................................. 30
Page 2 of 56
WAX for Windows ............................................................................................................................... 52 WAX for Linux ..................................................................................................................................... 53 Additional steps for SSL enabled sites ............................................................................................... 53
Changing the default WAX log location Configuring WAX advanced health monitoring
53 53
Configuring the health monitoring interface ........................................................................................ 53 1. Add trusted network clients to the list ............................................................................................. 54 2. Add the application pool user identity to the Performance Monitor Users group ........................... 54
56
Page 3 of 56
This information is not however specific to SharePoint, since the process of accelerating any website is essentially the same all websites are typically a combination of HTML, CSS, JavaScript, images or media objects such as animations or video and it is these objects that the Aptimize Accelerator helps tune the performance of.
Installation
WAX installs onto the web server(s) hosting the website, silently accelerating all responses to the user. At a high level, heres how traffic from the users browser flows through the Aptimize Accelerator in a typical hosting setup:
Page 4 of 56
Figure 3. WAX integration architecture The internal component architecture of WAX is described by the diagram below:
On the Windows platform, WAX integrates into the target website; installing as a combination of an ISAPI Filter and an HTTP handler (for IIS 6 and classic mode sites), and an HTTP module for integrated pipeline sites on IIS7+. The general process for each mode is the same:
Page 5 of 56
Since WAX intercepts and optimizes content after it has been rendered and is just about to be sent to the client, it doesnt matter what framework or technology your website uses. As long as it is made up of the basic components mentioned earlier HTML, CSS, JavaScript and images WAX will simply accelerate each response as much as possible. Since WAX works as a proxy, there are some basic requirements of the infrastructure for it to function: 1. The web server must be able to establish a connection with itself. This is typically possible without any configuration, but there may be security software that prevents this if this occurs, the security component must be reconfigured. 2. The user identity that the application runs as must be allowed to establish a connection with the local host. Again, this is the typical configuration so should be expected to work under most circumstances. Generally speaking, if you are able to connect to the server and open the site using a local browser then WAX will also have no problem. Its a good idea to have a specific hostname binding on each site, and a hosts file entry for this hostname since it allows for simpler testing on the server itself. If possible, this binding should accept connections on 127.0.0.1 as well as any other network address this guarantees no ambiguity where the IP address is a shared NLB address. This setup also makes it possible to run the performance analysis tools in WAX.
Configuration
Initial configuration of the accelerator on a target site is achieved by using the supplied configuration tool (found in the Aptimize programs group). This tool provides a simple graphical user interface over the underlying settings which are contained in an XML file called wax.config that lives in the site root directory. While most settings are available through the GUI, there are a number of advanced settings that can only be accessed through the wax.config file. This guide focuses principally on the manipulation of the settings directly via the wax.config file, since this provides maximum control over the accelerator behavior.
Page 6 of 56
In most cases, you will want to enter Expert mode and tune the settings to accelerate the site beyond what is possible using the default Safe mode settings. This can be done in the Aptimize configuration tool using the Safe / Expert mode radio selector.
Page 7 of 56
An acceleration profile is a predefined set of rules that have been determined by the Aptimize engineers to be required or desired to provide an optimal acceleration outcome for a particular platform. For example, the SharePoint platform requires some custom rules to prevent some images from being combined this is required since the URL of these images is manipulated in JavaScript, causing it to become malformed if it does not match the expected form. The SharePoint website profile also contains an additional rule to transform the contents of the /_layouts/init.js script to disable the IM presence script without this rule, a yellow security warning bar appears in Internet Explorer prompting the user to trust an ActiveX control which is not desirable in an internet scenario. When working in expert mode, the acceleration profile should be treated as a starting point there may be situations where you wish to override the default rules, so dont hesitate to change them if it makes sense to do so for the site you are tuning. It is however important to understand what the consequence of changing a rule will be, so you should familiarize yourself with the default profile rules and their effects. The configuration UI contains a number of options for tuning and analyzing the performance of the site this is covered in more detail later in this guide. For now, the next step is to verify that WAX is working as expected on the site.
The information displayed in this overlay is a report of what the accelerator did for the current page view. As such, it cannot show the result of things that did not happen this page view e.g. if background images were reported as being inlined into the StyleSheet the first page view, on subsequent page views this would not be visible since the already optimized StyleSheet would be served from cache so no actual work was done. This view is also useful to find out which combined set a particular individual object was added to.
Page 8 of 56
The time to first byte of 0.883s shows that the server responded relatively quickly it spent nearly a second generating the page, which is acceptable. If server processing to generate a dynamic resource exceeds 1 second, then it is worth running a code or database profiler to understand why this occurs this is outside the scope of this document but there are many good resources on the internet that cover this type of tuning.
Page 9 of 56
Page 10 of 56
Note: the action attribute is shown on its own above - a real configuration file would have many other attributes already present, so you should add action in addition to these other existing attributes. To save space, this is a common format for presenting example configurations.
Page 11 of 56
MatchType may be one of: Contains : If the URL location contains the text in Path then it will be considered to be a match. Wildcard : The Path expression will be matched against the URL location, with * treated as a wildcard. Regex : The Path is assumed to be a regular expression, matching against the URL location.
Action may be one of: Include : The matching URL will be included for acceleration, using the settings defined at this location. Exclude : Any matching URL will be ignored by the accelerator (i.e. the content will be unmodified). Strip : Any UI element that references a matching URL will be stripped . Only elements that are visible in the server-side document such as <img>, <script> or <link> tags can be stripped.
For example, this configuration will exclude all locations by default but will selectively accelerate anything in the /pages/ directory, strip a bad CSS file (for example it returns a 400 or 404), include all image files and resample JPEG images to 70% quality but not combine PNG images, and exclude any web service request.
<wax:configuration ... action=Exclude ...> <rules> <add path=/pages/ matchType=Contains action=Include /> <add path=dodgy.css action=Strip /> <add path=*.gif matchType=Contains action=Include /> <add path=*.png matchType=Contains action=Include combineImages=False /> <add path=*.jpg matchType=Contains action=Include jpegImageQuality=70 /> <add path=^(.*\.(asmx|svc)((/|\?|\.)[^jJ][^sS].*)?)$ matchType=Regex action=Exclude /> </rules> </wax:configuration>
Note: All configuration settings are case sensitive, so take care to get the capitalization correct when editing the wax.config file directly. The default matchType is assumed to be Contains, so if it is not specified then this will be the default.
Page 12 of 56
Transforming content
There are times where the underlying content of the site has errors, or is structured in such a way that it limits the optimal function of the accelerator. In this case, it is possible to apply any text based transform on the content prior to WAX attempting to accelerate it. You can add one or more transformations to any location specific rule as a child element (please refer to the Transformations section for more information on possible transformations). A tool such as the Fiddler client-side proxy is very useful when defining transformation rules, as the transformed content may be easier to see in the traffic log. WAX will also report which transformations were run for a particular page in the debug overlay view. Transform rules are a very powerful tool for fixing content on the fly here are some common scenarios in which this feature might be used:
Applying the following transformation rule to core.css, we can change padding to margin and the combined image will appear in the exact same position as when WAX is disabled.
<add matchType="Contains" path="core.css" action="Include"> <transformations> <replace pattern="\.articleimage\s*\{\s*padding-top:10px;\s*\}"><![CDATA[.articleimage{margintop:10px;}]]></replace> </transformations> </add>
Note: The default configuration does not enable HTML image combining, and therefore does not show this problem. You can enable image combining by setting combineImages=All in the wax.config file.
Page 13 of 56
Since the scriptaculous script is very small, the patched version is shown here in complete form if this were a more complex script, you could use replace transformation with a regex to remove or modify the content as required rather than a combination of clear + insert transformations.
Page 14 of 56
The autoUrlVersion transform uses the named capture called <url> in the regular expression, attempting to create a well-formed URL from it. If the URL is valid, then WAX will append a query string parameter containing the hash of the file contents this value will change every time there is a change to the file, causing the browser to request the latest version.
Transformation Tips
While many things can be achieved with transformation rules, there are some considerations that should be met when choosing to use one vs. actually fixing the underlying content issue: Running many transforms on non-cacheable objects is CPU intensive, so try to use transform rules on cacheable objects external to HTML pages. Some things cannot be fixed with a transform rule, e.g. you can never run an autoUrlVersion transform on a URL that is calculated by concatenating two variables together, since this is calculated by the browser.
Unless you consider yourself a regex master, you should also get a good regular expression evaluation tool that can show replacement test results clearly (search for regex tester on the web) this will save your sanity!
JavaScript debugging
In order to accelerate a site to the maximum extent, combining JavaScript files into as few files as possible is an important step. Some script files are sensitive to the order in which they appear in the page others have expectations about what various files in the page are named, so any changes can confuse them. It is therefore useful to be able to read JavaScript, and in particular to understand JavaScript error messages so that you can identify what the cause of any functional problems that appear when you combine or move JavaScript objects.
Page 15 of 56
If you are running in production, it is possible to define one or more trace keys that can be used to capture a verbose level of logging detail on demand, without capturing. For example, the following logging settings will allow the use of the special trace key called foo to capture a single debug trace.
<logging logInfoLevel="Info" > <trace key="foo"/> </logging>
To capture a verbose trace, the appropriate user would be instructed to request the problematic page, appending the trace key to the query string e.g.
http://www.example.com/pages/profile.aspx?waxtrace=foo
This is typically a better option than enabling logging at a global level, particularly if the site is in active use, since a very large volume of log data can be produced. Too much data makes it hard to identify the relevant information for debugging purposes. If you are tracking down an error message that is appearing when accessing the site particularly if immediately after installation then the error log is the place to look for detail on the cause. When in Development Mode, warnings will also be logged and will appear in the Health Check view these messages are not critical, but do indicate some problem that may limit the maximum possible performance of the site. For example, if a StyleSheet contains invalid CSS that WAX determines would make combining it with other StyleSheets impossible, then it will automatically be excluded. If WAX cant process a resource then it cant accelerate it, so this is something that is desirable to fix. Performance related problems can be diagnosed, in the first instance by using the performance log viewer this will give some indication of where the problem might be. A problem with the target website will show up as an extended duration in PageTime, or one of the components of it: Headers or FullContent if the problem is to do with the interpretation or acceleration of a page or resource then this will show up under Optimizer time, or one of its components e.g. CssOptimizer or ImageOptimizer.
Page 16 of 56
The Aptimize Accelerator product family helps you apply these 4 rules to any website quickly and without changes to the website code or content. The recommended technique is to start with the accelerator in safe mode, and then (assuming in safe mode that everything looks ok) incrementally turning features on as described below.
Analysis of this chart and the related table shows that there is room for improvement the chart x-axis measures load time in seconds, while the y-axis shows the objects that the browser loaded to display the page that was requested. The colors on the chart represent different activity within the browser:
Page 17 of 56
Rule 1: Reduce the time it takes for the server to respond to a request
This rule really only applies to the very first request in the waterfall graph since this is the server response to the page request. In this case, the server took around 900ms to generate the page content and start sending it. The recommended maximum for page generation is around 1 second if the server processing time pushes out beyond about 20% of the total load time, then any front end tuning done to satisfy the other 3 rules will start to become less meaningful. To get the server processing time down, you must look at server side resources and efficiency this could be a combination of hardware upgrades, server-side code profiling and tuning, and database query tuning. This is beyond the scope of this document, though there are many good guides in the public domain that discuss server-side tuning in detail. Note: Any server-side tuning effort can only ever affect the first line on the waterfall chart, so keep this effort balanced with front-end tuning.
Page 18 of 56
It is also possible to enable this setting using the configuration UI in the WAX configuration tool as shown in this screenshot. This demonstrates setting the CSS StyleSheet combination to All. Other CSS related acceleration settings are covered later in this document.
Combining StyleSheets is generally a safe and effective way of accelerating page load time. Below is a list of known possible issues and their resolution: Symptoms: - Page layout changes when combining StyleSheets Problem: - Inline style blocks appearing between external StyleSheet links - One or more StyleSheets contains invalid CSS and could not be parsed Resolution: - Move inline style blocks to the appropriate StyleSheet, or change StyleSheet combining to Consecutive to preserve the order of styles. - Use the health check view to identify the StyleSheet containing malformed CSS, and correct it either at source or by using a transform rule.
Page 19 of 56
Page 20 of 56
To prevent StyleSheets from growing too large, a threshold size for background image inlining is defined and controlled by the maxCssInlineSize setting. The default of 1200 bytes is a useful value for most sites the number of images inlined must be balanced with the size of the StyleSheet. Around 60kB is the recommended maximum compressed size for a CSS StyleSheet. This feature is controlled by the inlineCssImages setting and can be defined at the default location or any on other location specific rule:
<wax:configuration ... inlineCssImages=True ... >
Issue: The StyleSheet is very large, even with a very low maximum size threshold. Resolution: This is typically caused by a background image that is referenced from CSS on many different selectors. To overcome this, you can define a single CSS class that contains the background property, and combine this with any element specific styles on the same element e.g.
Page 21 of 56
to this:
<style> #foo { display:block; } .foo-bg { background-image:url(foo-bg.gif); } </style> <div id=foo class=foo-bg>this element has a background image style</div>
Wherever an element has a style that applies the foo-bg.gif image as a background, it should reference the foobg class.
HTML images
HTML images are those images that are referenced from an <img> tag in a page. To accelerate these images, WAX will create a sprite set that contains all images of a particular format. WAX then attaches some CSS style information to the <img> tag to reference this sprite as a background image, and sets the src attribute to reference a transparent gif - /wax.axd/cache/1x1. HTML image sprites can be enabled by setting combineImages to True. This setting and can be defined at the default location or any on other location specific rule:
<wax:configuration ... combineImages=True ... >
Like CSS and JavaScript settings, you can also control the behavior of image combination via the WAX configuration tool UI. The full list of options available for image acceleration is covered later in this document.
Possible problems that may be seen when combining HTML images include: Symptom: - A new sprite set seems to be created every time I visit the page. Problem: The list of images in the page is different every time, which causes WAX to create a new sprite set every page visit. Resolution: - Use the groupName attribute or named resource set (see below) to control which sprite set the various image resources appear in - Add a custom rule to include the dynamic images in an uncombined form (action=Include, combineImages=None )
Page 22 of 56
Any object that contains /_layouts/1033/ as part of the path will be grouped into a set called chrome, and all other objects will be grouped in an appropriately named automatic set. Objects may only be grouped according to their type and format in the case of images, and if the chrome images vary from page view to page view then this will not greatly help reuse in this case, you should use a named resource set.
Page 23 of 56
The objects in a named resource set must be specified as an absolute or root relative URL it should be possible to enter these URLs in a browser (prefixed with the host name if required) and have the item be successfully displayed.
The definition of what is a compressible resource is controlled by the compressableMimeTypes attribute, the default value of which is:
compressableMimeTypes=text/html,application/xhtml+xml,text/css,text/javascript,application/xjavascript,text/xml,application/xml,application/json,text/x-component
If you wish to add or remove items from this list, you will need to edit the wax.config file and specify the compressableMimeTypes attribute on the top level wax:configuration element or a rule element for a more specific path. The usage and customization of this setting is covered in the Compression section. Heres a simple example of a custom rule to enable compression for a custom file type:
<add path=.ext action=Include compressableMimeTypes=text/custom />
TIP: There are some objects that are by default not able to be shrunk by WAX but which can improve the website speed if they are. This includes Shockwave Flash or Silverlight animations both these formats allow developers to build large files that contain redundant content or code, rather than building controls that are targeted exactly to where they are used. For example, rather than building a 1MB flash animation that displays on the homepage of the site, but displays different content on internal pages, it would be better to build a 300kB file for the homepage, and allow another 700kB file to load for the internal pages. Optimizing this type is
Page 24 of 56
Additional mime types can be added to this list if there are objects that are not being cached, but which it is desirable to do so. Or, if the default list of cacheable mime types includes an entry that is not desired to be cached, then it can simply be removed. This setting can apply either at the default location or on any other location specific rule, allowing a single object to be marked as uncacheable if desired. This can be achieved by specifying for that location an empty cacheableMimeTypes setting, e.g.
<add path=/bar.swf action=Include cacheableMimeTypes= />
WAX applies different cache durations to resources depending upon how it is referenced, according to the following table: Condition Object is combined into a resource set Object URL was versioned by WAX Original object URL was requested Cache for 1 year 90 days 1 hour
The length of time that a resource is cacheable on the client for is controlled by the resourceClientCacheDuration attribute that can be applied either at a global or rule specific level for example, this rule could be specified to only cache objects on the path /volatile/ for 60 seconds:
<add path=/volatile/ action=Include resourceClientCacheDuration=60 />
This setting only applies to objects that have not been combined into a set of any kind resource sets are always cached for 1 year on the client. URLs that have been versioned by WAX are cached by default for 90 days. This represents the minimum time that these objects will be cached it is possible to use the resourceClientCacheDuration setting to increase the length of time however.
Page 25 of 56
In memory caching
WAX will also cache any object that is either compressible or cacheable in memory on the server, as long as there is sufficient RAM to do so. This can dramatically reduce the load on the server where the content is being sourced from a database backend, and improve the speed at which this content can be served. Changes to objects are automatically detected by WAX, according to the global resourceRecheckInterval configuration setting. The default recheck interval is 60 seconds this means that WAX will keep serving the original object for 60 seconds, after which it will replay the original request for that object to refresh the content. While the refresh operation is in progress, all requests for that object receive the previously cached version which allows no wait time for users. Once the refresh has completed, the new object will start to be served instead if the content has been altered in any way, then any reference to this object either from a combined resource set or from the versioned component of a URL will be recalculated, changing the URL that the browser sees. This allows changes made on the server to be received by browser clients within minutes of them being made, but until that time the browser will always use its own locally cached version, giving maximum performance.
Disk caching
Combined resource sets are stored in memory for fast serving when requested, but they are also written to disk when a cachePath is specified in the WAX configuration file. Since these combined object sets have a cost to produce, this conserves the resources of the server. It is also necessary to write combined resource sets to disk in a load balanced hosting scenario, where one server node receives a request for a page that results in a combined image set to come into existence, but another node in the load balanced cluster receives the request for that combined image set. In this case, the instance of WAX running on the second node must load the combined resource set from disk and add it to its own local memory cache before serving. More information on configuring a disk cache can be found in the section on production deployment see Specifying a cache path.
Page 26 of 56
While a webserver cannot obviously serve content for a site that it does not host, WAX can cause this content to be served from the origin site host in one of 2 ways: By combining the object into a resource set, since this is served from the WAX cache By versioning the URL, which will rewrite it to be served from the origin domain host
Serving content from the origin domain rather than a variety of domains can provide significant benefits: The content is likely to load significantly faster. Every distinct hostname used on a page requires additional DNS resolution time and TCP connection establishment time. You are also subject to the QOS characteristics of the external site, which for the kinds of external content that people regularly link to is often very poor. For example, links to social networking bookmark images, advertising network scripts, and partner logos are often very slow. The chance of some content being unavailable is greatly reduced. If a site links content from 3-4 other sites, then the chance of one or more resources being temporarily unavailable is greatly increased. With an external site that is not under your direct control you are always subject to outages of that site, or to routing issues where your origin site is accessible to the user but the external site is not.
Example X: Social networking site bookmarks The SharePoint sample site contains a section on the right hand panel just beneath the News section titled Share this. This is a fictional feature that allows users of the site to share the page on some major social networking sites. This functionality is implemented as a script that emits the HTML using document.write wherever it is placed in the page. While this is not good practice, it is a common technique that is used by web developers. WAX allows this situation to be overcome and these images to be combined wherever they are referenced by creating an image resource set and running a transform over the script file that inserts these images. The example configuration below also demonstrates referencing external content.
Page 27 of 56
This resource set will be used in place of any of its individual images, but only if they appear in an HTML <img> tag. We must use a transform rule to inject the details of the combined image resource into the bookmarks.js script file as shown below:
<rules> <add matchType="Contains" path="/bookmarks.js" action="Include"> <transformations> <clear /> <insert><![CDATA[ var html = "<h3 class='ms-standardheader ms-WPTitle'><span>Share this:</span><span>"; html += "<a style='padding:3px;' href='http://www.facebook.com'><img src='${1x1}' style='${imageset(Bookmarks,facebook,\")}' border=0 alt='Share on Facebook' /></a>"; html += "<a style='padding:3px;' href='http://del.icio.us'><img src='${1x1}' style='${imageset(Bookmarks,delicious,\")}' border=0 alt='Bookmark on De.licio.us' /></a>"; html += "<a style='padding:3px;' href='http://www.digg.com'><img src='${1x1}' style='${imageset(Bookmarks,digg,\")}' border=0 alt='Digg!' /></a>"; html += "<a style='padding:3px;' href='http://www.stumble-upon.com'><img src='${1x1}' style='${imageset(Bookmarks,stumble,\")}' border=0 alt='Review on StumbleUpon' /></a>"; html += "</span>"; document.write(html); ]]></insert> </transformations> </add> </rules>
First a clear transformation is applied to clear all content before sending the bookmarks.js file content. Then, an insert transform is applied in this example, the entire contents of the file are included in their patched form since the script file is so small. The insert transform evaluates and expands the ${imageset(SetName,ItemName,QuoteChar) expressions in the content, before sending the optimized version to the browser client. Note: Referencing external objects in a resource set does not require you to use specifiedDomains or AllDomains for the includeFromDomains setting value.
If your CDN host does not proxy the origin server then you would need to add a rule to prevent combined resources from being rewritten, such as:
Page 28 of 56
WAX will automatically use the scheme of the incoming request when accessing a CDN host, but it is possible to specify the scheme and virtual path in the rewriteToCdn setting if required. This allows the scenario of switching all traffic up to SSL if the target website is reverse proxied through another device that terminates the SSL connection. For example:
<wax:configuration ... rewriteToCdn=https://cdn.example.com/foo/ ...>
It also allows switching all static content down to HTTP if your user audience can be trained to accept the mixed mode content warning this can have a dramatic positive effect on performance due to the cacheability of plain HTTP URLs. Domain sharding and download parallelism It is possible to use the rewriteToCdn feature of WAX to perform domain sharding, allowing you to relocate some resource URLs to a second hostname that is in fact hosted on the same origin server by the same website. For example, if your current website is called www.example.com, your webserver will have a binding to accept requests for this hostname using domain sharding you would add a second binding to this site called images.example.com, or cdn.example.com, or any fictional domain name, and then register this name in DNS. Heres a sample configuration that would rewrite the URL of all images to images.example.com:
<add path=(.gif|.jpg|.png) action=Include rewriteToCdn=images.example.com />
While techniques that attempt to make browsers download more resources in parallel such as domain sharding can work under some conditions, they can in many cases cause worse performance so it is important to measure the effect of doing this. Note: WAX can only rewrite URLs that appear in the content as rendered by the server i.e. URLs that are evaluated by JavaScript cannot be changed automatically. It is however possible to use an autoUrlVersion transform or a simple text based transform on script content to rewrite this type of link to a different host.
Page 29 of 56
Testing tools
There are many great tools for verifying the speed of a website. The most useful tests are those that measure loading speed using a real browser, rather than a synthetic benchmark. These tools fall into 2 broad categories: Those that simulate user activity, but test from a variety of locations Those that integrate into the site and measure actual user load times
AOL webpagetest (http://webpagetest.org) is a great example of the first type of test tool and is free to use. As long as the site is publically accessible then this is a simple and effective option, that gives you a nice waterfall chart to work from or present in a before / after view to other stakeholders.
8. Deployment to Production
Once configured correctly, the Website Accelerator is designed to run continuously in a production environment without intervention. In summary form, the key things to ensure when moving to production are: Install the Website Accelerator + an appropriate license on each server and site required
Page 30 of 56
Below are the recommendations in detail for configuring the Website Accelerator for production hosting.
Page 31 of 56
Shared remote cache This mode is appropriate for single or load balanced environments, where cache redundancy is not essential (e.g. where you have a single database server, and web server nodes exist only for performance rather than redundancy). Any UNC based path can be used, as long as the user identity of the application pool as read/write/modify permissions to the remote file system and the remote share.
<wax:configuration ... cachePath="\\192.168.0.15\WaxCache" ...>
Replicated local cache This mode suits a cluster where redundancy is important. Each web server node must be configured with a local cache, into which resources are replicated from other nodes in the cluster as required. The example below shows a configuration where all nodes use a path called C:\WaxCache\SiteX to store their local copy of cached resources, and the cluster definition that allows the Website Accelerator to find remote nodes and replicate cache content as required.
<wax:configuration cachePath="C:\WaxCache\SiteX"> <cluster cacheMode="Replicated" networkPath="WaxCache\SiteX" > <node hostName="Foo" /> <node hostName="Bar" /> </cluster> </wax:configuration>
Note: On the Linux platform, this function is handled by the Apache module so the networkPath attribute is not required. The function of each of these settings is as follows: cacheMode: May be "Shared" or "Replicated". When the cluster element is not present, Shared is assumed. networkPath: This is the share name plus any child path beneath the share (Windows only). The remote server name / IP address should not be included in this setting as this is combined with the hostName of the node. hostName: Specifies the DNS name, either short or fully qualified, of each host node in the cluster. This name will be used to communicate with the WAX module, or combined with networkPath to form the full share path to find remote resources. zone: (Optional) Defines the zone that a node lives in. Any host will escalate a cache lookup to nodes in the same zone first before looking at nodes in other zones. On the Windows platform, the share identified by network path must exist on all nodes in the cluster, with the application pool user identity being granted read permission on the share (i.e. no remote write permission is required).
Page 32 of 56
The More details link provides detailed information about the cause of any problems. You should always run the Verify Cluster step whenever you add or remove a node from the cluster. Nodes that are taken out of load-balancing rotation for servicing or due to failure should be removed from the list prior to being made unavailable. This ensures that WAX will not attempt to communicate with these nodes while they are out of service. If performing a new install, it is possible to run this test with WAX switched Off this allows you to verify that the configuration of each server is correct before switching WAX on and starting to accelerate requests.
Page 33 of 56
The default value of 100MB is typically sufficient for most sites, but if you notice a lot of cache thrashing in the WAX monitoring statistics then try increasing this number. The cache eviction rate should not typically exceed more than a few hundred objects per minute. More information about monitoring the internal WAX performance counters is available in the section on configuring WAX advanced health monitoring.
WAX automatically cleans up log files when they exceed the default maximum number of hours to be kept, but if your site is very busy then these log files may be many megabytes. Under normal conditions, as long as your system drive has plenty of space then the default location is fine to store these files if you plan to run a global debug trace in production under load, then you probably want to move your logs first as this can produce large amounts of trace data. The duration that log files will be kept for can be controlled by the settings in the logging section.
Page 34 of 56
SQL Reporting Services SharePoint webpart displays an error when WAX is installed
When viewing a page with the Reporting Services SharePoint webpart displaying a report, an error message is displayed stating execution [random_numbers] not found. The error remains even after switching WAX off. Problem: - Reporting Services uses a URL reservation within http.sys to provide access to the report data, but this conflicts with the Aptimize ISAPI filter. Resolution: - Uninstall WAX from the target site, and install in Proxy mode instead (see Running WAX in proxy mode for more information).
Page 35 of 56
Page 36 of 56
Page 37 of 56
Page 38 of 56
Logging section
The logging section allows control over the logging behavior of WAX. The logging element itself allows 4 possible attributes to be defined: logInfoLevel [optional] Error Only important errors will be logged by WAX. Errors at this level are also reported via the system event log. [default when in Production Mode] Warning In addition to errors, any condition that may affect the performance of the site, but which will not affect behavior for end users will appear at this error level. Info In addition to errors and warning, the Info error level will display other information about the internal workings of the accelerator specific to the site it is installed on. [default when in Development Mode] Trace Resources on specified domains only will be optimize (see the SpecifiedDomains section below). retainPerformanceLogDuration [optional] [Number] The number of hours to retain the performance log information for. [default = 24] retainErrorLogDuration [optional] [Number] The number of hours to retain error log information for. [default = 5] retainDebugLogDuration [optional] [Number] The number of hours to retain debug log information for. [default = 5] The logging section also allows the definition of a set of trace keys that can be used to capture specific requests. These are defined as inner elements of the logging element refer to the Logging and debug trace section for usage information.
Monitoring section
The monitoring section controls the behavior of the advanced health monitoring status API, exposed via the URL: /wax.axd/api/status. The following attributes are allowed on the monitoring element: enabled [optional] False Health monitoring information will not be available in the status True Health monitoring information will be available via the status API. trustedClients [optional] [Text] A comma separated list of IP addresses or partial network addresses that are trusted to query the status API. By default, only requests from the localhost address will be allowed. probeMaxDelay [optional] [Number] The maximum number of milliseconds to delay the response of the status API request when queried by an upstream load balancer. [default = 100]
Page 39 of 56
ResourceSets section
The resourceSets section may contain one or more set elements that define a group of objects that should always appear together. The set element allows two unique properties to be defined: type [required] ScriptSet The resource set should be treated as a collection of JavaScrip objects. StyleSheetSet The resource set is a collection of CSS StyleSheet objects. GifImageSet The resource set is a collection of images in GIF format (automatically converted). PngImageSet The resource set is a collection of images in PNG format (automatically converted). JpgImageSet The resource set is a collection of images in JPEG format (automatically converted). name [optional] [Text] The name that this resource set should be known as when referencing it from within any transform rule. In addition, all feature settings that are applied on custom rules may also be applied to the set element. Global settings will be used by default, then overridden by settings specified on the set element. The set element may contain one or more add elements, which like the set element accepts any feature setting to override the settings defined at higher levels. The add element requires that the path attribute contains either an absolute URL or a URL that is relative to the site root so that it can be pre-fetched by WAX.
SearchEngineCrawlers section
The searchEngineCrawlers section may contain one or more add elements that define the user agents of known search crawlers. Any user agent that is not a browser will normally be served the original site content, but by
Page 40 of 56
If your site is not publically accessible, this section can be removed entirely from the configuration file.
SpecifiedDomains section
The specifiedDomains section allows a select set of domains to be defined that govern the eligibility of resources to be processed by WAX. If the hostname of an object URL does not match an entry in specifiedDomains, then it will be excluded otherwise, the URL will be tested against any rules that might also apply, and if included will be accelerated.
<specifiedDomains> <add path="example.com"/> <add path="www.example.com"/> <add path="images.example.com"/> </specifiedDomains>
The path attribute is required when defining the list of specified domains.
Rules section
The rules section allows a list of location specific rules to be defined that override the global settings. These rules are processed in the order in which they appear (i.e. top to bottom) with the first match terminating further processing, and the settings at that location being applied. Each location specific rule is represented by an add element within the rules section. The add element has 3 primary components: path [required] [Text] The pattern that should be matched against when evaluating URLs against this rule. The format of this pattern will depend upon the matchType being used. matchType [optional] Contains The path attribute should be treated as a text fragment, with any URL that contains that fragment considered to be a match. [default] Wildcard The path attribute should be treated as a wildcard expression, where any asterisk symbol matches any number of characters. To allow a wildcard to match any URL, it must begin and end with an asterisk. Regex The path attribute is a regular expression that should be tested against the URL for a match. action [required] Include Any resource URL that matches this rule should be included by WAX for acceleration. The type of acceleration applied will depend on the resource type.
Page 41 of 56
Transformations
The add element of the rules section may also contain a transformations element that allows a set of transform rules to be applied at the location when a match is made:
<rules> <add matchType="Contains" path=".js" action="Include"> <transformations> <!-- put transformations in here --> </transformations> </add> <rules>
There are two types of transformations that can be run on a location specific rule: Raw content transformations This group of transformations are run prior to the content being processed by WAX, so can be used to fix any semantic problems with for example CSS or HTML prior to parsing. Valid raw content transforms include: clear Allows you to clear the content of a resource. This can be useful if you have a resource that you wish to completely replace the existing content. An example of this would be a bootstrapping JavaScript file which separately loads a number of other script files. Instead you could clear the content of this script, then using the insertUrl transform insert the actual content of the scripts that the bootstrapper would normally load.
Example: <clear />
autoUrlVersion Allows you to auto version any URL that matches a particular pattern. This can be useful for ensuring that resources loaded from JavaScript can be URL versioned. pattern [required] A regular expression, the URL to capture should be stored in a capture group named <url> (must be XML encoded). with [required] A regex replace expression to reinsert into the page once auto versioned. The new URL can be added with the substitution token ${url} (must be XML encoded). rootUrl [optional] The root URL to make all URLs found relative to.
Page 42 of 56
insert Allows you to insert content to the start or the end of a document, this can be useful for changing the behavior of scripts but is particularly useful for altering StyleSheets by inserting styles at the end of a StyleSheet, thereby overriding the behaviors defined earlier in the StyleSheet. insertionPoint [optional] Either the Start or End of the document [default = End] content [required] Specified as the inner text of the element, this text will be inserted at the location identified by insertionPoint. This content should be wrapped in a CDATA section.
Example: <insert insertionPoint="End"> <![CDATA[<!-- secret footer comment -->]]> </insert>
insertUrl Allows you to insert content from another document to the start or the end of a document. This can be useful for combining the content of a number of separate files into a single file if the standard WAX combination techniques arent suitable. This can also be used to silently redirect requests for one URL to another URL. insertionPoint [optional] Either the Start or End of the document [default = End] url [required] The URL of the resource that should be retrieved and inserted into the content body.
Example: <insertUrl insertionPoint="End" url="http://example.com/custom.js" />
replace Allows you to replace content which matches a particular pattern. This transform is extremely versatile and has a wide range of possible uses. These include altering content that is causing combination errors, changing script behaviours, and altering stylesheets. One common scenario is converting javascript document.write statements which write out script tags ito actual script tags so that those scripts can be combined. pattern [required] A regular expression that matches the content to be replaced (must be XML encoded). content [required] Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.
Example: <replace pattern="foo"> <![CDATA[bar]]> </replace>
HTML content transformations HTML content transformations run once the raw content has been parsed into an HTML document. This type of transform is typically more efficient than running raw content transformations as they only modify small sections of a document at a time, rather than running regular expressions over the entire document content. For this reason it is recommended that parsed content transformations should be used where possible instead of raw content transformations. clearElement Allows you to clear the content of a parsed html tag. This is useful for removing certain script blocks from a page, or clearing out the content of a script block before replacing its content with something else via one of the other parsed content transformations. name [required] The name of the HTML element to match (one of style, script, img, link, or input).
Page 43 of 56
insertElement Allows you to insert content to the start or the end of a matching element. This is useful if you want to append or prepend content to a specific element in an HTML document. name [required] The name of the HTML element to match (one of style, script, img, link, or input). id The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip If no id is specified, this specifies how many matches to skip past before first applying the transformation. take If no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account [default = 0 which takes all matches] removeContainer True to remove the containing element from the document, or False to leave it intact. insertionPoint The Start or End of the document (default = End). content [required] Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.
Example: <insertElement name="script" id="foo" removeContainer="True" insertionPoint="End"> <![CDATA[nothing to see here...]]> </insertElement>
insertHtml Allows you to insert content at various points in an HTML document. This is useful for injecting styles or script blocks to certain parts of a page. insertionPoint [required] The location to insert the content into the document (one of HeadStart, HeadFirstScript, HeadLastScript, HeadEnd, BodyStart, BodyFirstScript, BodyLastScript, BodyEnd). content [required] Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.
Example: <insertHtml insertionPoint="BodyEnd"> <![CDATA[My custom footer]]> </insertHtml>
removeElement Allows you to remove a parsed html tag from a document. This is useful for removing redundant or problematic script and style blocks from a page. name [required] The name of the HTML element to match (one of style, script, img, link, or input). id The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip If no id is specified, this specifies how many matches to skip past before first applying the transformation.
Page 44 of 56
moveElement Allows you to move a parsed html tag to another location in a document. This is useful for moving script blocks to a more optimal location. name [required] The name of the HTML element to match (one of style, script, img, link, or input). id The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip If no id is specified, this specifies how many matches to skip past before first applying the transformation. take If no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account [default = 0 which takes all matches] insertionPoint [required] The location in the document to move the element to (one of HeadStart, HeadFirstScript, HeadLastScript, HeadEnd, BodyStart, BodyFirstScript, BodyLastScript, BodyEnd).
Example: <removeElement name="script" id="foo" insertionPoint="BodyEnd" />
replaceElement Allows you to replace content that matches a particular pattern for a selected element. This transformation, like the more general replace transform has a wide range of uses, but is more appropriate if you have content that you wish to replace that resides in a particular element on a page. name [required] The name of the HTML element to match (one of style, script, img, link, or input). id The id of the HTML element to match on. To specify other attributes to match (e.g. href or media) then use id="href=style.css" or id="media=print". You don't need to specify the attribute if you want to match an id e.g. id="foo". pattern A regular expression that should be tested against the content of the element for a match. This should only be used if an ID does not exist on the element you wish to match (must be XML encoded). skip If no id is specified, this specifies how many matches to skip past before first applying the transformation. take If no id is specified, this specifies how many matches to run the transformation for once the first match is found (after the skip setting has been taken into account [default = 0 which takes all matches] removeContainer True to remove the containing element from the document, or False to leave it intact. content [required] Specified as the inner text of the element, this text will be used to replace the section of the original content that matched the specified pattern. This content should be wrapped in a CDATA section.
Example: <replaceElement name="script" id="foo" removeContainer="True" pattern="red"> <![CDATA[blue]]> </replaceElement>
Cluster section
The cluster section defines the collection of web servers that operate in a cluster to host the target sites. The cluster element itself accepts two attributes that control the behavior of the cache when running in a load balanced cluster: cacheMode [required] Shared The path specified in the cachePath attribute is treated as a shared network path that all servers will use to store and find combined resources where an in-memory cache miss occurs.
Page 45 of 56
Feature settings
Settings that apply either at the default location or on a location specific rule are described in detail below.
General
canonicalization [Text] A regular expression that should be applied to the URL prior to it being tested against other rules. This regex should capture just the part of the URL that is considered to be its canonical components into a named capture called <url> (must be XML encoded). contentType [Text] Allows the native content type (MIME type) as returned by the web server to be overridden. This can be useful if content is being emitted by a server side component in the wrong form, since WAX will not process content of one kind where it expects the content type to be another. For example, it is possible to mark all .js files with contentType=text/javascript if one or more is appearing as text/html. groupName [Text] Defines the name of the group that resources will be added to when combined instead of using the default global group names. This allows objects to be partitioned into common and page specific images for example. httpFetchTimeout [Number] Defines the maximum time in milliseconds that WAX will wait for a resource to be retrieved. All local resources of the site are expected to be returned effectively instantaneously, so if this limit is being hit there is probably something wrong. There are however legitimate cases where a longer timeout is desirable, particularly if WAX is instructed to process resources from external sites.[default = 3000]
Page 46 of 56
CSS optimization
shrinkCss True CSS blocks in the page and in external StyleSheets will have all redundant whitespace + comments removed. False CSS will remain in its original form wherever it appears. Note: this disables the ability to use the inlineCssImages setting. inlineCssImages True Background images that are referenced from CSS will be converted to data:uri notation and inlined as base64 data into the CSS for browsers that support it. For Internet Explorer 6 & 7, this feature will use an MHTML reference instead of data:uri notation. False Background images that are referenced from CSS will remain as URLs instead of base64 data. maxInlineImageSize [Number] The maximum allowable size of base64 encoded data to be inlined using data:uri notation or a MHTML reference. Images that exceed this will limit will remain as URLs. combineStyleSheets None StyleSheet files will not be combined together at this location. All All StyleSheet files will be combined together, no matter where they appear in the page, and the new combined reference will be inserted at the top of the head section of the document. Consecutive StyleSheet files that appear as consecutive references (i.e. without inline style blocks or excluded StyleSheet links between) will be combined together and each combined reference inserted to the location where the first StyleSheet in a set appears in the document. combineInlinedCssImages Off Disables the creation of MHTML references for IE6 and IE7 browsers, leaving browsers that support base64 data:uri notation enabled. This setting is automatically applied when the page is requested over HTTPS, since otherwise IE displays a mixed-content warning. PerStylesheet WAX will produce one MHTML document containing the base64 encoded image data per StyleSheet. PerCombinedStylesheet WAX will produce one MHTML document containing the base64 encoded image data per combined StyleSheet. [default]
JavaScript optimization
shrinkScripts True Script files will have all redundant whitespace + comments removed. False Script files will remain in their original un-minified form. combineHeadScripts None Script files that appear in the head section of the document will not be combined together with other script files. All All script files found in the head section of the document at this location will be combined together into a single file.
Page 47 of 56
Image optimization
combineImages None Images that appear as <img> tags in the HTML will not be combined into image sprites. All All images that appear as <img> tags in the HTML will be combined into an image sprite according to the image format. imageFormat Gif The image will be converted to GIF format before being added to an image sprite or served. Png The image will be converted to PNG format before being added to an image sprite or served. Jpg The image will be converted to JPEG format before being added to an image sprite or served. Note: If an image appears on a website in BMP format, it will automatically be converted to JPEG format by WAX to reduce its size. This can be prevented by excluding the image from processing with a rule.
Page 48 of 56
Caching
cacheableMimeTypes [Text] A comma separated list of the MIME types that should be considered cacheable at this location. The default list is: text/css, text/javascript, application/x-javascript, image/gif, image/png, image/jpeg, image/jpg, image/bmp, image/x-icon, application/x-shockwave-flash, text/x-component. resourceClientCacheDuration [Number] The duration in seconds that resources in the cacheableMimeTypes list at this location should be cached for on the client before expiring. This is used as a sliding expiry to set the Expires header i.e. the client will cache the file for this many seconds from when it receives it, whenever that is. [default = 600 for unversioned URLs, i.e. 10 minutes 7776000 for versioned URLs, i.e. 90 days] autoVersionUrls True URLs at this location will be versioned by appending a query string parameter that is a hash of the contents of the file. The cache duration used for versioned URLs is the greater of resourceClientCacheDuration or 90 days. False URLs will be left unaltered (clients will cache the item for the full resourceClientCacheDuration interval before rechecking). proxyCacheable True Resources that are cacheable at this location will be marked with the Cache-Control: public header which allows them to be cached by intermediary proxy servers. False Resources that are cacheable will be marked with the Cache-Control: private header to prevent them from being cached by intermediary proxy servers. [default] resourceRecheckInterval [Number] The time in seconds after which a resource that is in the server cache will be marked for a recheck. When a resource that is marked this way is requested, the existing version in cache will be returned immediately, while a background task refreshes the cached version if it has been modified.
Compression
compressableMimeTypes [Text] A comma separated list of the MIME types that should be considered compressible at this location. The default list is: text/html, application/xhtml+xml, text/css,text/javascript, application/xjavascript, text/xml, application/xml, application/json, text/x-component.
Page 49 of 56
Logging
suppressedErrorCodes [optional] [Text] A comma separated list of WAX error codes that should be suppressed at this location. If you see an error code in the logs that you wish to silence, you can specify just the number component of this here.
Page 50 of 56
This will disable the use of MHTML resources, which affects only IE 6 & 7 users all other browsers will still leverage data:uri inlining of images. If there are only parts of a site that are SSL secured, you can specify this setting on a location specific rule instead. This allows MHTML inlining to be used except where it is known that users will access the site over HTTPS.
Page 51 of 56
The method of running WAX in proxy mode differs between the Windows and Linux versions of the product.
5. Save the file, and hit F5 in the WAX configuration tool to verify that the config is valid 6. Run IIS manager, and move the bindings from the target website to the WAX_Proxy site (you will need to remove them from the target and add them to the WAX_Proxy site)
Page 52 of 56
WAX will rotate the log files it produces to prevent them from taking up an increasingly large amount of disk space, but if you have trace level logging enabled at a global level on a production site, this can still result in a very large amount of data in the log files. Moving these log files to a separate drive will prevent the system drive from running out of space.
Page 53 of 56
2. Add the application pool user identity to the Performance Monitor Users group
To enable the Aptimize Accelerator to gather system performance information, the application pool user identity that the website runs under must be a member of the Performance Monitor Users group. Adding the application pool user identity to this group differs depending upon the operating system used. Once this user has been added to the Performance Monitor Users group the application pool must be restarted to cause the Aptimize Accelerator to start sampling the performance counters. Windows 2003 Server / Windows 2008 R1 Server For the site you want system performance information for, determine the user account that the application pool is running as from IIS Manager. For Windows 2003 Server, you must navigate to the Identity tab of the application pool properties dialog on Windows 2008 Server the user identity is visible from the Application Pools list. To add the user to the Performance Monitor Users group, you must use the Computer Management administration console (Start -> Run -> compmgmt.msc). Expand the Local Users and Groups node, select the Groups node, then right-click Performance Monitor Users and select Add to Group.
Select the local computer as the location if the application pool is using an in-built account, or the appropriate domain if it is a domain account, then enter the name of the user account and click Check Names. If the account is found by the operating system it will change the formatting of the name once this is done click OK.
Page 54 of 56
Once you have added the user account to the Performance Monitor Users group, you must recycle the application pool for the changes to become visible to the Aptimize Accelerator. Windows 2008 R2 Server / Windows 7 On Windows 2008 R2 Server and Windows 7 operating systems, the default user identity use for all application pools is ApplicationPoolIdentity. This represents a virtual account that is created by IIS using the name of the application pool prefixed with IIS AppPool for example, the SharePoint application pool in the screenshot below can be referred to in ACL lists using "IIS AppPool\SharePoint".
To add the correct user account, you must select the local computer from Locations and then enter the name of the virtual account as demonstrated in the screenshot below. This dialog is accessed via the Computer Management administration console (refer to the instructions for Windows 2003 / 2008 R1 above).
Page 55 of 56
You may also need to enable compression within your ADC appliance. Please refer to the documentation for your particular make and model for guidance on how to configure this. You should inspect the HTTP traffic to ensure that all text based resources are being correctly compressed afterward this can be confirmed by the presence of a header called Content-Encoding on the response. If compression is enabled, this should contain the value of either gzip or deflate.
Page 56 of 56