Confluence has Performance Issues During the 'Creating Word File' Export Step for Large Exports

Symptom

Whenever large exports are performed, especially with lots of images/tables, Confluence has severe performance issues during the 'Creating Word File' phase.

Cause

When Word exports include large amounts of content that must be rendered, the creation phase can consume a lot of memory and affect the performance of Confluence.

Resolution

To reduce the performance hit, you can configure Scroll Word Exporter to perform the 'Creating Word File' step in a separate process. This is an external conversion process executed in a separate Java Virtual Machine (JVM).

These steps should only be taken by system administrators. Configuring the options in this guide incorrectly can cause performance and stability issues in your Confluence instance.

Alternatively, Confluence administrators can also apply export restrictions to spaces/user groups and/or restrict the number of pages that can be exported.

Step 1: ensure your server has enough memory

As a rule of thumb, you need at least 8GB of free memory to implement this setting. This means that, after taking in account all the processes running on your server, which may include;

Confluence
System processes
Database
Memory reserved for non-heap usage
Any other processes that you may be running

You should have at least 8GB of free memory, otherwise, running the conversion process externally will probably not improve performance/stability.

Step 2: configure the external conversion process

Once you've determined that you have enough memory, you can configure the external conversion process using advanced plugin settings at General configuration > Scroll Runtime > Advanced Plugin settings > Scroll Word Exporter:

Advanced plugin setting Description How to configure

word.conversion.external.
pageThreshold

Configure how large an export must be for the external process to be used.

To never process PDF exports externally, set to -1
To always process PDF exports externally, set to 0
If set to any non-zero, positive number, the conversion is external if the number of exported Confluence pages is greater than or equal to that number. There's no set-in-stone rule regarding how high this number should be – but you can make a rough estimate based on the number of pages and the type of content included in these Confluence pages which previously triggered the performance issues.

word.conversion.external.
jvmArguments

You can use this setting to control the amount of memory the external process uses (and any other arguments for the Java Virtual Machine (JVM) used for the external conversion process).

The amount of memory you assign here should be 25% of the total amount of memory you want to assign to the external rendering process. This is because by default, Scroll Word Exporter supports up to 4 parallel exports. We recommend assigning no less than 8GB in total, which means assigning 2GB on this setting → for large exports (eg. 500+ Confluence page) we would recommend assigning more than 2GB.
In order to prevent the parallel garbage collector from consuming a lot of CPU resources on all your cores, you may want to use the serial garbage collector for the conversion process. This constrains the conversion load to fewer cores. This can be achieved by adding -XX:+UseSerialGC to the JVM settings in the advanced plugin settings.

Please see Oracle's documentation on JVM command line arguments for Unix or Windows for further details.

Practical Examples

In the examples below we assume that the virtual machine hosting Confluence does not run any other memory-intensive applications such as databases or other Atlassian software (Jira, etc.). If you do run such software you need to consider their memory requirements as well when calculating the optimal value.

Setup	Configuration options
Virtual machine has 32GB of ram Confluence has 5GB of ram assigned	External Conversion Process (`word.conversion.external.jvmArguments`) has 5GB assigned 4 Parallel Export remain configured (4 * 5GB for conversion processes) Apply these settings in advanced plugin settings CODE `-Xms512m -Xmx5g -XX:+UseSerialGC`
	External Conversion Process (`word.conversion.external.jvmArguments`) has 8GB assigned 2 Parallel Export remain configured (2 * 8GB for conversion processes) Apply these settings in advanced plugin settings CODE `-Xms512m -Xmx8g -XX:+UseSerialGC`
Virtual machine has 64GB of ram Confluence has 8GB of ram assigned	External Conversion Process (`word.conversion.external.jvmArguments`) has 10GB assigned 4 Parallel Export remain configured (4 * 10GB for conversion processes) Apply these settings in advanced plugin settings CODE `-Xms512m -Xmx10g -XX:+UseSerialGC`
	External Conversion Process (`word.conversion.external.jvmArguments`) has 15GB assigned 2 Parallel Export remain configured (2 * 15GB for conversion processes) Apply these settings in advanced plugin settings CODE `-Xms512m -Xmx15g -XX:+UseSerialGC`