Performance Tuning

dotCMS makes every possible effort to deliver a well-tested, out of the box configuration that works in most situations without requiring any special configuration. However depending on the nature of your site, you may want to make specific configuration changes to improve site performance.

There are many factors to consider when performance tuning dotCMS, and as with most computer performance considerations it may require some trial and error. dotCMS runs on many different combinations of hardware and operating systems, and can be configured with a huge variety of open source and custom features and code. Each of these have specific options and performance considerations, and you will have to discover the best options to meet the business and performance needs of your site.

With that in mind, here are a number of areas of your dotCMS configuration that you can review to tune and improve performance.

Performance Settings

Java Virtual Machine (JVM) Settings

Since dotCMS is a Java application, it's important to ensure your JVM settings are set properly to achieve optimal performance.

Tomcat Application Server

By default, dotCMS runs on the Tomcat application server shipped with the dotCMS distribution. The dotCMS Tomcat distribution configures the JVM based on the JAVA_OPTS environment variable, and you can modify the options in this variable to adjust the amount of memory used by your JVM and to configure features and options such as garbage collection.

The following shows the Java options set in the default dotCMS distribution (Linux version):

set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true -Xverify:none -Dfile.encoding=UTF8 -server -XX:+DisableExplicitGC

rem Set Memory sizing
set JAVA_OPTS=%JAVA_OPTS% -XX:MaxMetaspaceSize=512m -Xmx1G

rem Set GC opts
set JAVA_OPTS=%JAVA_OPTS% -XX:+UseG1GC

set JAVA_OPTS=%JAVA_OPTS% -Djava.endorsed.dirs=%DOTCMS_HOME%/WEB-INF/endorsed_libs

rem Set agent opts
set JAVA_OPTS=%JAVA_OPTS% -javaagent:%DOTCMS_HOME%/WEB-INF/lib/byte-buddy-agent-1.6.12.jar

However if there is a JAVA_OPTS environment variable set before dotCMS is run, dotCMS will take the value of that environment variable instead (and will not set any of the above options). Therefore, if you wish to change the Java options, you may do one of the following:

• Set a JAVA_OPTS system environment variable before starting dotCMS.
• Modify the Java options in the script used to start dotCMS (in the bin directory in the dotCMS distribution folder)
  • Linux: startup.sh
  • Windows:
    • When started as an application: startup.bat
    • When running as a service: wrapper.conf

Other Application Servers

To change the JVM settings on other application servers, you may use the same command line options when starting Java; however the names of files and environment variables will vary depending on the application server used and how it is configured. For more information, please see the documentation for your specific application server.

Memory Limits for Plugins and Custom Code

In the dotCMS distribution, the default setting for the Java MaxMetaSpaceSize property is 512 mb. This limit ensures that your dotCMS instance will not run out of memory by growing too large for your server memory. However if you have a significant amount of custom or plugin code, this may not provide enough space for your code to run without hitting memory limits within Java, and you may need to increase this limit.

Database Configuration

Database performance can have a significant impact on dotCMS performance, and it is very important that your database is configured for maximum performance, especially for large sites.

Follow this link to learn how to configure your database connections within dotCMS.

In addition, please see the following for resources on performance tuning your specific database:

• PostgreSQL
• MS SQL
• Oracle (Support discontinued as of 22.03.0)
• MySQL (Support discontinued)

Important

The H2 database supplied with dotCMS is intended for demonstration and evaluation purposes only. It is not intended for production sites, and should not be used when evaluating or optimizing performance.

Cache Configuration

One of the most important areas impacting performance of large sites in dotCMS is the cache. dotCMS Enterprise editions allow customization of cache providers and settings to optimize performance. Follow this link to learn how to configure the cache.

Specifically, there are a number of cache regions which need particular attention when tuning performance, especially for large sites and sites with high utilization of some specific features.

Cache Region |

Logging Configuration

Log file messages can provide significant help when troubleshooting and debugging problems, but during normal operation excessive logging can significantly impact performance, especially on large systems. The following changes to logging configuration may help to improve performance.

• Modify Log File Paths to point to a SSD or other fast storage device.
• Change the Log Level of the Root Logger and as many other loggers as possible to Reduce Message Frequency.
• Ensure that log messages are not being written to the Console Output
  • Note that console output of dotCMS messages is disabled by default, but please also see the Application Server Log Files documentation about application server logging configuration.
• Add New Loggers and Log Files to separate log messages into a greater number of smaller log files.
• Implement Filters (such as the Burst Filter) to selectively limit which messages are written to the log files.
• Change the configuration of the Application Server Log Files to eliminate logging to the console and reduce messages written to the application server log files.

Logging Slow Performers

In addition to these measures which can improve the performance of logging itself, you may also use certain logging features to help identify issues in other features which may be reducing performance. For more information on each of these logging features, please see the Special Logging Configurations documentation.

• ElasticSearch Slow Query Logging
• Rules Feature Slow Rule Logging
• SQL Query Logging

Permissions Configuration

When Permissions are changed on a high-level object in dotCMS (such as a Site or top-level folder), the Permissions must be updated also for all lower-level objects which inherit Permissions from the object which was changed. For performance reasons, dotCMS performs all Permissions changes to lower-level objects “lazily” by default, meaning that the lower-level object Permissions are updated only when the lower level object is accessed.

However in earlier versions of dotCMS, Permissions updates were performed “eagerly” (meaning all the Permissions changes on all lower level objects were performed immediately), and dotCMS contains a configuration parameter which can be set to revert to the former behavior (which can have a negative impact on performance).

To ensure that Permissions changes have a minimal impact on performance, verify that the PERMISSIONS_REFERENCES_INSERT_LAZILY property in the dotmarketing-config.properties file is set to false.

PERMISSIONS_REFERENCES_INSERT_LAZILY=false

Profiling

The Logging Slow Performers section (above), gives links to documentation sections describing how to identify slow Elasticsearch queries, Rules, and SQL queries. In addition, you may perform profiling on the following additional areas with potential for a performance impact in dotCMS:

• Startup Time Profiling
• Execution Time Profiling
• Java Memory Profiling

Startup Time Profiling

Each time you start dotCMS, the amount of time taken by each phase of the startup process is measured and recorded. if the startup times for your dotCMS system are longer than expected, or appear to be increasing, you can use these values to help identify both which phases of the startup process take the most time, and if the length of any phases of the startup process are increasing over time.

To view the startup profiling information, select System -> Maintenance, and open the System Info tab. Below the Environment Variables section, the following values will be displayed in the list of dotCMS system variables:

Notes:

• All startup times are recorded in milliseconds.
• The startup times are also saved to the system.properties file (dotserver/tomcat-X.x.x/webapps/ROOT/WEB-INF/classes/system.properties).
  • To track the startup measurements over time, you can review copies of the system.properties file in your backups, or save copies of the file periodically.

Execution Time Profiling

dotCMS ships with the open source Glowroot profiling library to enable easy execution profiling of both the dotCMS code and your plugin code. However for security and performance reasons this library is disabled by default.

Several configuration properties control basic settings of the included library, detailed below:

Detailed logging settings are stored in the configuration file glowroot.logback.xml, located in the glowroot/ folder inside the Tomcat folder (e.g., ${project.basedir}/src/main/resources/container/tomcat9).

In a Kubernetes environment, remote collector address and agent ID are required. For example, your orchestrator file might contain:

- name: 'GLOWROOT_ENABLED'
  value: 'true'
- name: 'GLOWROOT_AGENT_ID'
  value: 'your-site::master'
- name: 'GLOWROOT_COLLECTOR_ADDRESS'
  value: 'http://glowrootcentral.example.com:8181'

For more information on using Glowroot, please visit the Glowroot web site.

Java Memory Profiling

You can use JConsole to profile the memory use of dotCMS. Simply uncomment the following line in the startup.sh/startup.bat file and restart.

JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote.port=7788 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false"

Important: If you are having memory troubles and want to see what is happening in realtime this is an invaluable tool, however java profiling significantly reduces performance. Your site will suffer a performance hit as long as the profiler is enabled, so make sure to comment out the line again once you are done.

For more information on tuning Java performance, please see the Java Performance Tuning White Paper.