Page display performance tips and techniques - 7.x


Confluence allows more advanced users to construct pages that bring in data from various sources and present the data in nice ways like charts and tables. Unfortunately, some of these types of pages can be very slow to render for users. Fortunately, there are a number of advanced techniques that can be used to significantly improve page rendering performance or restructure pages to provide a better user experience. This page provides some hints and tips for improving performance to render complex pages


Render is the Confluence process that takes page markup and converts it into html that is sent to the browser. In simple terms, the time taken to display the page in the browser is determined by:

  • Server processing - Confluence server processing that converts page markup into html
  • Download time - to transfer the html and all referenced images, scripts, and related information to the browser
  • Browser - rendering time


Cache for Confluence is constrained by:

  • The amount of CPU needed to do the server work - this is primarily a single threaded activity and can only be improved by single processor rates.
  • Communications bandwidth which can be variable depending on time and location.
  • Browser performance with FireFox considered to be generally faster than Internet Explorer (IE).

Factors to address

Cache for Confluence is:

  • Most impacted by page construction techniques to reduce processing load.
  • Addressed by reducing the size of the rendered text and images.
  • Addressed by browser options (caching) and by pages that best optimize browser capabilities (like caching).

Server processing

It is important to note that all the elements of a page must be rendered even if portions of the page are not displayed initially. For instance, if you use constructs that have tabs or have expand and contract sections, all the data in those sections still must be rendered. Generally, the display of the data is controlled by the browser with no further interaction with the server (an exception is delayed rendering discussed below). This means that pages with a large amount of data that is gathered and processed but not shown immediately to the user may be wasted processing if the most likely user interaction is to not look at that tab or hidden section.

Use page links verses tabs

Providing a link to a page instead of a tab improves performance by only rendering the data when the user explicitly requests to see it.

Delayed rendering

This is a technique to allow the browser to display the page while processing continues with the rendering of portions of page data. Use the future macro to delay processing of portions of the page. These areas of the page display a loading message until the data is available from the server.

Extracting data from other systems via SQL or other techniques can take a significant amount of time. Similarly for metadata reporting. Is the data static or dynamic? Does it need to be current to the second or just to the day, week, or month?

Use caching

Cache Macro allows data to be extracted once and the rendering re-used for subsequent access to the page. The cache macro parameters allow you to control the length of time the data is cached. Care must be taken to not overuse this capability as there is limited amount of memory allocated to the cache across the system. You can optionally provide the user with a refresh button to give them control over the trade-off between the currency of the data and time to display. Recommend only using the refresh option in limited cases, as it is likely to be used and then the user has to wait again. Advanced users (authors) can force a refresh anyway by using a request parameter - add ?refresh=true to the page url (sometimes &refresh=true must be added instead if the url already has a request parameter specified).


The cache macro is smart enough to invalidate the cache if you edit the contents within the cache macro. It also invalidates the cache if any attachments are changed on the page. For example, if a newer version of the excel spreadsheet is attached, the cache is invalidated automatically and the new spreadsheet data is brought in. There is a parameter that controls this behavior - checkAttachments that has a default value of true to cover the case just mentioned above. However, attachment checking should be turned off (checkAttachments=false) if this feature is not needed and MUST be turned off if taking advantage of chart attachments (see below)!


Be careful with using caching on pages that present data to some users but not others. Users with more authority can produce cache data that can be viewed by a different user at a later time. This also applies to references to data or attachments from other pages. The authority for producing the cache is based on the user that is viewing the page when the cache has expired. There are techniques to address this as well by providing multiple views of the data, one for each group, each with there own cache. The show-to and hide-from macros can be used.

Converting data from other formats into charts and tables can be expensive. The cache macro can help here too, but there are special considerations for charts. The chart macro converts the chart data into an image that is then sent to the browser to display.

Save chart images

There are advanced chart macro parameters for attachments that allow chart images to be automatically rendered and saved. Similarly for Graphviz graphs.

Letting the user make an explicit choice before viewing information that is expensive to produce can sometimes provide a better user experience. Instead of producing a page that has all the data that the user may need, let the user specify their specific need for data first.

Let user control information request

Use the Run macro to provide a simple dialog for the user to request data. Once the user requests the data, the data is rendered and presented based on the parameters the user provides.

Download time

The techniques above in many cases also help with download time. Pages with less data download faster. Providing page links to data spread out the interaction time over a number of requests. A balance must be made to ensure the user gets the data they normally want without an excessive amount of clicking.


The caching techniques above also help with browser performance. Browser locally caches static images.

FireFox is generally viewed as performing better that IE. Ensure you are using the latest browser (no matter what your browser choice).


Lots of static charts

If you have a lot of charts that are relatively static (only change occasionally), the best approach is to save the chart image as an attachment and re-use this image for subsequent viewing. This is easy to do:

  • Add the following parameters to your chart macro:
    • attachment=your attachment name.png - this stores the chart image as an attachment to the page (or optionally another page)
    • attachmentVersion=keep - this tells the chart macro to only render the chart data and redraw the image if the attachment referenced by the attachment parameter does not exist
  • How can the chart be regenerated? Just delete the attachment and view the page to get it to regenerate the attachment.
  • Should I use the cache macro too? No, not in this case unless there is some other reason to use it on the page.

Lots of data gathering

SQL data, excel data, or metadata reporting are expensive (time) operations. If the data is static or it is acceptable for it to be a bit out of date, then use the cache macro specifying the refresh period appropriate for your situation.

  • How can the data be regenerated?
    • Add showRefresh=true to the cache macro to provide a button for users to press to get a refresh
    • Or add ?refresh=true to the url for the page in the browser - this can be used by advanced users (usually page authors) or be included in a link provided by the author on some page

Dynamic data gathering used for charts

Decide on an acceptable amount of time the data can be out of date - it might be hours or minutes. Suppose it is 1 hour.

  1. Use the cache macro:
    • refresh=1h - this means the data is retrieved if older than 1 hour
    • checkAttachments=false - this says the cache is used even if attachments have been changed on the page
  2. Add the following parameters to your chart macro:
    • attachment=your attachment name.png - this stores the chart image as an attachment to the page (or optionally another page)
    • attachmentVersion=replace - this tells the chart macro to replace the attachment that represents the chart

How can the data be regenerated? It is the same case as just using the chart macro.

Mixture of static and dynamic data

Use a combination of the above techniques but narrowed to cover the data of each type.

Multiple portions of a page

If the page has multiple portions that each can take a while to render and the techniques above do not apply, use the future macro around the later portions of the display so that the user perceives that the page is available quicker even though more data gathering is taking place in the background. This is especially useful for data displayed in tabs. (Note: the tab to be displayed may not be the first one since the tab the user last used on a previous visit may be shown first.)

Automated caching

The first user to view a page after the cache period has expired can be delayed a significant amount of time while the cached data is being refreshed. One way to mitigate that is to have a background process that can cause the cache to be replenished on a regular basis. The trade-off is additional processing that takes place even if no one is viewing the page verses a faster initial display. One technique is to have various pages with different automated refresh times. By adding an include on the time refresh page, that include page is rendered as well. Alternatively, the automation can just have a list of pages with refresh times. Here is an example of standard refresh times:

  • every 15 minutes
  • every hour
  • every 3 hours
  • every day (6:00am)
  • every week (Sunday)
  • once a month (first day of month)


Confluence Command Line Interface (CLI) can be used to render the page using something like:

confluence --action renderPage --space demo --title "my title"

Furthermore, Run CLI Actions in Bamboo makes it easy to schedule automatic updates using Bamboo. Otherwise, use your favorite job scheduler.