Performance Tuning 3.x

Theme Builder is now used on some extremely large and popular wikis - both behind corporate firewalls, on the public Internet and even the world's largest privately owned hospital ship! As your wiki becomes more widely adopted, things that used to work quickly may start to become bottlenecks and your configuration of Theme Builder is no exception.

Whether you've got 20,000+ users or 10,000+ spaces, there's always a way to maintain the performance of your wiki and Theme Builder. This page contains information on the most recent techniques for improving performance of the theme element of your wiki and contains links to performance tips from previous versions of the theme which are still relevant.

We've done some of it for you!

Whilst most performance tuning will be specific to the way you are using Theme Builder, there are certain elements that we can deal with within the theme itself.

Building on the existing Theme Builder 2.x performance tweaks, we've built in even more enhancements:

• The average theme design now only uses 5 external JavaScript files instead of 11
• More resources are using Cache Expire (1 year)
• Theme layouts contain much more intelligent caching on the server to reduce processing time
• The default View and Edit menus are 3 times faster thanks to compound items
• We've waded through the HTML, JavaScript and CSS with all manner of diagnostic tools and made huge numbers of improvements throughout the plugin
• We've refactored huge swathes of the Java code used in the plugin to make it cleaner, faster and more maintainable

... more to follow ...

Use fewer macros

As a result of Theme Builder 2.x, we found out that every macro has an overhead caused by the work Confluence has to do to process it... A surprisingly large overhead which quickly mounts up if you're using lots and lots of macros on every page!

The more macros you add in to your theme layouts, the slower the theme will be regardless of how fast those macros are. Before a macro is even executed, Confluence has to do all kinds of work (parsing parameters, wiki rendering the macro body, etc) so you need to use macros carefully and sparingly.

Remember that when you add macros to layout panels, they'll be executed for every user on every view of every page that uses that layout. That's going to hammer your server.

However, you probably wouldn't be adding macros to the layout if there wasn't a need for them. So what can you do to solve this dilemma? Well, there are a number of solutions...

Use the cache macro

The cache macro allows you to cache the output of a macro. On subsequent views of the same page, if a cache is found then it's used instead of reprocessing the macro (or other wiki notation encapsulated by the cache macro).

But be careful - if you've got macros that output different things based on user privileges, you could end up caching the output for one user and then showing it to everyone else. For a much more detailed explanation with examples, see Menu Performance Tuning.

Only show when required

There are numerous macros that can show and hide content only when it's needed based on factors such as location within the wiki, labels, user privileges, etc.

Wrapping your panel content, as applicable, in these macros means that you can still display the macros when required, but not on every single page thus reducing the strain on the server and bandwidth.

The most common macros are:

• builder-show macro and builder-hide macro
• show-to macro and hide-from macro
• show-if macro and hide-if macro

Use compound menu items

If you use the menuitem macro, menulink macro and menuicon macro a lot, try converting your markup to use the new compound-menuitem macro which can reduce the number of macros used by two thirds (from 3 to 1)!

When you consider the number of menu items in the default view and edit menus alone, you can quickly imagine how this will have a very noticeable beneficial effect on performance. You can make most menu items three times faster simply by using the new compound-menuitem macro!

The default menu notation output by the viewmenu macro and editmenu macro has been updated in Theme Builder 3.0 and above, however if you've altered the notation or moved links out in to other locations, etc., you should certainly consider converting your notation over to the new compound format.

Likewise, if you've imported a theme designed in an earlier version of Theme Builder, it'll be using the old menu notation that used a lot more macros.

See Also: View Menu 3.x and Edit Menu 3.x

Avoid CSS imports

In earlier versions of Theme Builder, it was difficult to have one master CSS file that would be used across multiple spaces so many of our clients created a css file and imported it in to the Custom CSS using the CSS @import directive.

Well, due to the new Layout Inheritance feature on Theme Builder 3.x you can now easily define a master CSS file directly within the Custom CSS (and IE CSS) settings then re-use and even extend that CSS across multiple spaces and theme layouts. We've even made the CSS text boxes resizeable for easier editing!

Start by creating a "master layout" (in the Layout Manager) that will contain your main style sheet. Using the CSS Tab, paste in your CSS and then save the layout.

You can immediately apply that layout to multiple spaces (personal and global) and also at global level (dashboard, etc). If you change the CSS in the layout, everywhere that uses the layout will use the updated CSS.

Furthermore, you can easily re-use that CSS in other layouts if required by creating a "child layout" in the Layout Manager. The child layouts will automatically inherit the CSS from their parent layout. If you change the CSS in the parent layout, the CSS in the child layouts is automatically updated.

Note: Ensure you have the "Merge this layout's CSS with it's parent's CSS" option ticked to ensure the child layout inherits the CSS from the parent layout.

You can now add CSS that's specific to the child layout and it will be output along with the CSS from the parent layout (the parent CSS is output first allowing the child CSS to override bits of the parent CSS if desired).

Go Low Level

Macros and wiki notation are effectively high-level elements - they sacrifice performance in order to be easier to use.

If you want to gain performance, you're going to have to use something a little more complex...

HTML, XSLT, etc

There are a range of macros that take advantage of widely used technology such as HTML (see html macro and html-include macro) and XSLT etc.

These generally require that you understand the syntax of whatever technology they offer, but require far less processing time on the server.

User Macros

Confluence allows you to create "User Macros" in the Administration Console. These allow you to more safely add raw HTML content to your wiki and also allow you to take advantage of the Velocity engine to perform basic scripting, etc.

Scriptix

Note: This plugin requires the latest production version of Java (version 6) – which is not yet officially supported by Atlassian for use with Confluence. That being said, we're now using it on several sites.

Adaptavist's Scriptix plugin allows you to create server-side scripts in languages such as JavaScript, PHP (Quercus), Python (Jython) – in fact any scripting language listed here.

Because Scriptix uses Java 6, it enables much tighter integration with Java and even allows compilation to byte code of PHP scripts – giving the potential to run even faster than mod_php.

Extreme Measures

If you've got a huge wiki with lots of Spaces and content, or if you've got huge numbers of users accessing your wiki, you'll need to start looking at the server hardware and Confluence itself to take performance tuning to the next level.

Server Hardware

The easiest way to boost performance is to upgrade bits of your server (or even just buy a shiny new one):

• RAM - Java applications like Confluence love RAM. It's a very quick way to squeeze some more performance out of an existing server that's struggling under the workload. If you have over 1GB of RAM in your heap and you're still running out of memory – profile the dumps for memory leaks.
• Faster disk drives - if you use macros that make heavy use of the search index (you'd be surprised how many do this!) or database then investing in a faster disk drive will help boost performance. We generally use 2 or more 7200RPM SATA drives in RAID 1/5 configuration via a hardware RAID controller.
• Faster processor - A faster processor will, erm..., process things faster! For best results invest in a multi-processor 64-bit server with modern multi-core processors.

Clustering Confluence

We made Theme Builder 3 clusterable for a reason If you are following these guidelines, you need to cluster will mainly come from the desire for high availability to reduce the risk from hardware failure.

Other Options

There are a vast array of other options, including changing or optimising your application container (eg. Tomcat or Resin), operating system, database and cache settings.

If you host or access the database and/or file system on another server using something like NAS, you'll likely be adding a huge amount of latency, compared to local storage, as a result. Instead of using remote file storage, look at pushing the attachments into the database and taking manual backups – this will substantially reduce the amount of size needed for the Confluence home directory (potentially multiple TB reduced to under a 100 MB).

See Also

Most of the content of earlier performance tutorials are still applicable to Theme Builder 3.x:

• Performance Tuning 1.x
• Performance Tuning 2.x
• Menu Performance Tuning