Performance Tuning - Documentation topics on: cache,database,java,log4j,performance tuning,profiling,velocity page profiling,.

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 dotCMS 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.

JAVA_OPTS="-Djava.awt.headless=true -Xms512M -Xmx512M -XX:PermSize=128m"

To set the JAVA_OPTS environment variable, you may do one of the following:

  • Create a JAVA_OPTS system environment variable.
  • Modify the script used to start dotCMS (in the bin directory in the dotCMS distribution folder)
    • Linux:
    • 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.

Database Configuration

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

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.

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.

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.

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 file is set to false.



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

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:

dotcms.startup.msThe total dotCMS startup time.
dotcms.startup.cache.msThe total time required to initialize all cache regions.
dotcms.startup.db.msThe time required to start up and connect to your database. time required to start Elasticsearch and load all indexes.
dotcms.startup.quartz.msThe time required to start the quartz scheduler and scheduled jobs.
dotcms.startup.osgi.msThe total time required to start all OSGI dynamic plugins.


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

Java Profiling

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


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.

Velocity Page Profiling

Sometimes performance issues are limited to a subset of pages, and the biggest challenge is to find these pages. To find these problematic pages dotCMS provides a Velocity page profiler. To enable it, you need enable DEBUG logging on the com.dotmarketing.velocity.VelocityServlet$PageProfiler class. This can be done on the log4j2.xml file, by inserting a logger:

    <logger name="com.dotmarketing.velocity.VelocityServlet$PageProfiler">
        <level value="debug"/>

Alternately you can enable Velocity page profiling on a running server by using JMX. To do this, pass com.dotmarketing.velocity.VelocityServlet$PageProfiler as a parameter to the enableDebug operation of the org.dotcms.Log4J MBean.

When Velocity Page Profiling is enabled, messages similar to the following will be written to the log file, displaying the time taken for the Velocity code to run for each page:

[11/09/09 10:18:17:017 EDT] DEBUG velocity.VelocityServlet$PageProfiler: VelocityPage time: 17 millis