Work with Server Monitor

The ColdFusion Server Monitor lets you track activities on a ColdFusion Server. You can identify information about the server, including requests, queries, memory usage, and errors. You can start and stop collecting server information and take snapshots of the server.

To track the status of more than one ColdFusion server, use the Multiserver Monitor.

The Server Monitor and Multiserver Monitor provide information about your ColdFusion servers. Generally, the information that the Server Monitor provides is more detailed than the information that the Multiserver Monitor provides. However, the Multiserver Monitor provides a good way to track the status of multiple ColdFusion servers.
The Server Monitor provides information about the following:

• Requests, queries, sessions, and threads
• Response time
• Memory usage
• Alerts and errors
• Snapshots of server information
  The Multiserver Monitor provides the following information:
• Requests
• Response time
• JVM memory usage
• Alerts, errors, and time outs

Starting the ColdFusion Server Monitor

The ColdFusion Server Monitor is a SWF application that you access from the ColdFusion Administrator. The Server Monitor begins gathering and displaying data when you start it.

The ColdFusion Multiserver Monitor is a SWF application that can provide information about more than one ColdFusion server. To gather detailed information about one ColdFusion server, use the Server Monitor. To gather information about several servers, use the Multiserver Monitor.

Start the ColdFusion Server Monitor

1. Start the ColdFusion Administrator.
2. Select Server Monitoring > Server Monitor, and then click Launch Server Monitor.

Start the ColdFusion Multiserver Monitor

1. Start the ColdFusion Administrator.

2. Select Server Monitoring > Server Monitor, and then click Launch Multiserver Monitor.

By default, server monitoring is turned off. To start and stop monitoring, profiling, and memory tracking, click the corresponding buttons in the top bar of the Server Monitor. The following table indicates what data the Server Monitor collects when you click the Start button:

Viewing Server Monitor Reports

When you start the Server Monitor, the Overview page appears. To return to the Overview page from any other page, click Overview.
By default, the Server Monitor retrieves data for graphs every 5 seconds; it retrieves data for reports every 30 seconds. All the graphs let you display either all the data collected, or the data collected for a specified recent period.
The Server Monitor lets you control the detail, which you turn on and off with the following buttons:

• Start Monitoring Turns on all monitoring.
• Start Profiling Turns on monitoring of individual tags, functions, and query execution times.
• Start Memory Tracking Turns on tracking of memory that different scopes use. If Profiling is also on, the Server Monitor tracks the memory that individual tags, functions, and queries use. Turning on or off monitoring, profiling, and memory tracking determines which data the Server Monitor gathers. For example, all the query reports require that you turn on profiling. The performance effect of turning on monitoring and profiling is minimal; however the performance effect of memory tracking can be significant.

Overview

The Overview page appears when you start the ColdFusion Server Monitor. It provides an indication of the overall performance of the server, and displays the following reports:

• Average response time Total response time divided by the number of requests. Click the drop-down list to view data collected since the server started, for the past 5 min, or for the past minute.
• Requests per second Number of requests per second. Click the drop-down list to view data collected since the server started, for the past 5 min, or for the past minute.
• Slowest active requests Lowest active requests that are slower than the threshold set on Slowest Requests page. The number of requests in the list depends on the report size set on the Slowest Requests page.
• Alerts Lists any alerts. To specify when an alert is generated, select Alerts > Alert Configuration. Alerts indicate whether your server is approaching an unresponsive state or if it is running slowly.
• Last errorMost recent error that any application generates on the server that is in the included paths specified on the Filter Settings page. In addition, the Summary page lists the other reports available. To view a different report, click its name. The available reports are:
  • Requests with errors
  • Requests that timed out
  • Requests slower than 20 seconds
  • Requests that use more than 40MB
  • Sessions that exceed 4KB
  • Queries slower than 20 seconds
  • Queries slower than 10 seconds on average
  • Queries that exceed 20KB

Statistics

Request Statistics

The Request Statistics section contains the following reports:

Active Requests

The Active Requests report lists all currently active requests that take longer to load than the request interval for reports specified in the Refresh Interval setting. Requests include browser requests, CFC HTTP requests, web services, gateways, and Flash remoting. You can view a list, a detailed view, or a graph of active requests. The detailed view includes the CFML stack trace, which you can use to find deadlocked requests and where a long running request is blocked. To see all request graphs in one view, click Chart. The graph indicates the number of requests that the server is currently processing and the number of requests that are awaiting allocation of an application server thread to begin execution. If the graph indicates that many requests are queued, you might want to increase the size of the thread pool. Alternatively, if ColdFusion is deployed in a cluster, you may want to add a server instance for more efficient load balancing.

Active ColdFusion Threads

The Active ColdFusion Threads report lists all currently active threads. You can view a list, a detailed view, or a graph of active threads.

Slowest Requests

The Slowest Requests report lists the slowest requests. You can specify the threshold that determines whether a request appears on this page. The lower the threshold, the more requests appear on the list. Use the Report Size option to limit the number of items in the list. You can view a list or a detailed view of the slowest requests. The detailed view includes the CFML stack trace. For more information, see Request handling.

Slowest ColdFusion Threads

The Slowest ColdFusion Threads report lists the slowest ColdFusion threads. You can specify the threshold that determines whether a ColdFusion thread appears in this report. As the threshold decreases, the number of requests in the report increases.

Active Sessions

The Active Sessions report lists all active sessions. You can view a list, a detailed view, or a graph of active sessions. The graph displays the active sessions and the number of users logged in to the server.

Cumulative Server Usage

The Cumulative Server Usage report lists the requests that have cumulatively used the most CPU time on the server. Even if a request runs rapidly, if it runs frequently, it can consume a large proportion of CPU time. Tuning requests with high cumulative server time can provide server-wide performance benefits. You can view a list, a detailed view, or a graph of cumulative server usage. Use the Report Size option to limit the number of items in the list.

Highest Hit Counts

The Highest Hit Counts report lists the requests that have the highest hit count. You can view a list or a graph of requests with the highest hit count. Use the Report Size option to limit the number of items in the list.

Template Cache Status

The Template Cache status report shows information about the template cache to indicate how it is performing. The template cache is where ColdFusion stores compiled CFM and CFC templates in memory. When a template is executed for the first time, it is compiled to Java bytecode, and then stored in the template cache. As long as the template is unchanged, ColdFusion uses the compiled form of the template stored in the template cache. The Template Cache status page lets you monitor the cache-hit ratio, which indicates the number of cache hits in relation to the number of cache misses. Cache hits are the templates retrieved from the cache. Cache misses are the templates that must be compiled before being placed in the cache. A server that is performing well should have more cache hits than misses, which is a high cache-hit ratio. If the cache-hit ratio is too low, you might want to increase the cache size by selecting Server Settings > Caching in the ColdFusion Administrator. For more information, see Caching. The Template Cache page also lets you monitor the number of templates in the cache, and the estimated memory that the cache occupies.

Request Throttle Data

The Request Throttle Data report lists all requests that the ColdFusion server throttles. Requests are throttled when ColdFusion queues them, because not enough total memory is available to handle them. Requests smaller than the specified limit are not queued or counted as part of the total memory. Requests larger than the specified limit are counted as part of total memory and are queued if the request throttle-memory size of the request is exceeded. The default value is 4 MB. To change the throttle threshold and memory, select Server Settings > Settings in the ColdFusion Administrator.

Memory Usage

The Memory Usage section contains the following reports:

Memory Usage Summary

The Memory Usage Summary report displays a graph that shows the estimated memory consumption by persistent scopes on the server, including the server scope, the application scopes, and the session scopes. If your server is consuming too much memory, the graph provides information about which scope is using too much memory, and when the increased memory consumption began. Detailed reports let you examine estimated memory consumption for the server scope and all active application and session scopes. For more information, see Variable memory usage.

Requests by Memory Usage

The Requests by Memory Usage report lists the requests that use the most memory. You can view a list or a detailed view. The detailed view lists the variables that use the most memory during the execution of the request.

CF Threads by Memory Usage

The CF Threads by Memory Usage report lists the ColdFusion threads that use the most memory.

Queries by Memory Usage

The Queries by Memory Usage report lists the queries that use the most memory. When a query appears in this report, you might want to tune the query to reduce the size of the result set, or cache the query to reduce memory consumption and network traffic. This report does not include information about cached queries.

Sessions by Memory Usage

The Sessions by Memory Usage report lists the sessions that use the most memory.

Application Scope Memory Usage

The Application Scope Memory Usage report lists the application scopes that use the most memory. The detail lists the application scope variables that use the most memory.

Server Scope Memory Usage

The Server Scope Memory Usage page lists the server scope variables that use the most memory.

Database

The Database section contains the following reports:

Active Queries

The Active Queries report lists all currently active queries that take longer to load than the threshold specified on the Slowest Queries report. You can view a list or a detailed view.

Slowest Queries

The Slowest Queries report provides the Slowest Queries report and the Slowest Queries by Average report. Both reports let you identify queries by template name and line number. The slowest queries report shows specific instances of a query that is slow, along with the SQL statement for the query. The detail view includes the SQL statement. This information lets you determine why an instance of that query was slow. The Slowest Queries by Average report indicates queries that are slow on average. This report does not provide the SQL code for the queries because the SQL statement might vary from one instance of the query to another. Cached queries are not included in either report. To improve performance, tune the queries listed in these reports. If the result of a query is static, you can improve performance by caching the query using ColdFusion's query cache. For more information, see Database response time.

Cached Queries

The Cached Queries report lists the queries that were cached. You can view a list of cached queries or details about an individual query. If the execution time of a query is low, determine if you really need to cache it. If the execution count is high, tune the cachedafter and cachedwithin settings of the query.

Query Cache Status

The Query Cache Status report graphs the number of cached queries, the estimated memory that the query cache consumes, and the query cache-hit ratio. Performance increases as the query cache-hit ratio increases. If the cache-hit ratio is too low, you might want to increase the size of the query cache. Alternatively, to analyze how your application uses the query cache, determine whether you can tune the cachedAfter and cachedWithin attributes of the cfquery tag. If the query cache is too large, determine if you can move some queries out of the cache.

Pool Status

The Pool Status report lists the data sources, whether an application on the ColdFusion server is using the data source, and the number of connections. You can view a list of data sources or details about an individual data source.

Most Frequently Run Queries

The Most Frequently Run Queries report lists the queries that were made the most. Even if individual instances of a query run rapidly, tuning queries with a high frequency can result in improved performance. This report does not provide information about cached queries. You can view a list of queries or details about an individual query.

Errors

The Errors section includes the following reports:

Requests with Errors

The Requests with Errors report lists the templates that generate an error. The report includes the path of the template, and the number of times errors occurred in that template. For the most recent error, the report indicates the time of the error, the error message, CFML stack traces, and Java stack traces. You can view a list of templates or details about an individual template. The detailed information includes the CFML stack trace.

Requests Timed Out

The Requests Timed Out page lists the templates that timed out. The report includes the path of the template, the number of times the template timed out, the most recent response time for the template, the time when the template was most recently used, the most recent estimated request size, and the CFML stack trace. A Java stack trace is not provided because time outs can only occur within CFML. You can view a list of templates or details about an individual template. The detailed information includes the CFML stack trace.

Alerts

The Alerts report lists all the snapshots that alerts generate.

Alert Configuration

The Alert Configuration page lets you specify the thresholds for when to generate an alert. Alerts provide warnings of potential problems, including a slow server or an unresponsive server. The slow-server alert is triggered when the server's average response time exceeds a specified limit. The unresponsive-server alert is triggered when more than a specified number of threads are busy for more than a specified number of seconds. The unresponsive-server alert creates a snapshot file, which lets you determine where request threads are unresponsive. Both types of alert let you run a custom CFC when the alert is triggered, which lets you provide your own automated response to an alert condition. You can specify whether to send an e-mail notification when an alert is triggered, and to whom. You can also specify the user name and password to log in to the server that is specified on the Mail page of the ColdFusion Administrator.

Snapshots

The Snapshots report lists all snapshots that are triggered. Snapshots include details about the ColdFusion server at the moment the snapshot is triggered. These details include:

• The time and reason the snapshot was triggered
• Whether profiling and memory tracking are enabled
• How many running and queued requests exist at the moment of the snapshot
• Information about memory usage, including:
  • JVM memory usage
  • Server, application, and session scope memory usage
  • Throttle-queue size and memory usage
• Information about cached queries
• Status of the database pool
• The Java stack trace
  Snapshots are triggered when one of the following occurs:
• You click Trigger Snapshot on the User Snapshots page of the Server Monitor
• The threshold for either an unresponsive server or a slow server is exceeded
  When you click Trigger Snapshot, the Server Monitor collects the information for the snapshot and saves it in a file named snapshot_usrgen_timestamp.txt in the cf_root/logs/snapshots folder. When the Server Monitor creates a snapshot, it saves the information in a file named snapshot_sysgen_timestamp.txt in the cf_root/logs/snapshots folder.

Specifying Server Monitor Settings

To specify the settings to use to generate reports, click Settings.
You can specify the following:

• How often to refresh Server Monitor reports
• How often to refresh Server Monitor graphs
• How often to calculate average response times
• Whether to show the entire template path
  To specify what file paths to exclude and include in monitoring and whether to monitor the ColdFusion Administrator, click Settings, and then click the Filter Settings tab. 
  To specify what file paths to exclude from profiling, click Settings, and then click the Profiling Filter tab.
  By default, the Server Monitor collects information about all ColdFusion templates in the webroot directory and its subdirectories and in any directories specified on the Mappings page of the ColdFusion Administrator. However, you might not want to monitor all requests on the server. You specify a path to exclude so that the Server Monitor does not collect information about files in that directory or in any of its subdirectories. This capability is especially useful in restricting monitoring on production servers. Use the Include Paths option to monitor any subdirectories of an excluded directory.
  To specify an alias for a template path, click Settings, and then click the Aliasing tab.

ColdFusion Server Monitor API

Use the Server Monitor API to programmatically retrieve all the data that the Server Monitor collects. The servermonitoring.cfc ColdFusion component contains methods that you call to perform Server Monitor tasks. For example, use the getAverageResponseTime method to get the average response time for the server.

To view the methods, method arguments, and documentation for the Server Monitor API, use the CFC Explorer. To do so, go to http://localhost:8500/CFIDE/adminapi/servermonitoring.cfc.

Using the Server Monitor API

Example

The following example uses the Server Monitor API to list the data sources to which the ColdFusion Server is connected and the number of connections:

Using the Server Monitor to improve server performance

The Server Monitor provides information that you can use to help improve the performance of your ColdFusion server.

Find bottlenecks in your application during development

1. Turn on monitoring, profiling, and memory tracking.
2. Set the Slowest Request and Requests By Memory Usage report thresholds to zero (0).
3. Run your templates.
4. For each request, find the following:
   • The slowest tags and functions in the Slowest Requests report.
   • The largest variables in the Requests By Memory Usage report.

JVM memory usage

Because ColdFusion is an enterprise Java application, the Java Virtual Machine (JVM) is the software component that most influences performance. Different JVMs from different vendors and different versions of the same JVM from the same vendor have different performance characteristics. You might benefit from changing the JVM that you are using with ColdFusion.

ColdFusion contains an embedded version of Tomcat as the application server and the Sun 1.6 version of the JVM. By contrast, ColdFusion for J2EE running on IBM WebSphere Application Server uses the JVM that WebSphere is configured to use.

To configure ColdFusion to use a different JVM, edit the cf_root/runtime/lib/jvm.config file with a text editor by modifying the value of java.home to point to the root directory of the JVM to use. Alternatively, you can switch to a different JVM in the ColdFusion Administrator on the Java and JVM Settings page.

Because switching the JVM changes the software environment significantly, do so first in a development or testing environment. Also, fully test your ColdFusion applications before you make the change on a production server.

The JVM performs memory management and can have a significant effect on your performance depending on how you configure the JVM. The most important settings for the JVM are the initial heap size and maximum heap size. The initial heap size represents the amount of memory that the JVM uses on startup; the maximum heap size represents the amount of memory that the JVM can use. You can modify these settings in the ColdFusion Administrator on the Java and JVM Settings page. The Initial Memory Size setting specifies the initial heap size; the Maximum Memory Size setting specifies the maximum heap size. The JVM arguments for initial heap size and maximum heap size are -XmsNm and -XmxNm respectively, where N is the size of the heap in megabytes (MB). These JVM arguments are stored in the jvm.config file, in the value of the java.args setting.

The default maximum heap size is set to 512 MB in ColdFusion. For best performance, set the initial heap size and the maximum heap size to the same value. Determining the optimal size for the heap to run the applications on your ColdFusion server results in improved performance. Setting the value too high can result in poorer performance because of the higher degree of garbage collection and internal memory management required for the larger heap. Conversely, setting the heap size too small can result in a java.lang.OutOfMemoryError error if your application tries to use more memory than is available to it.

The best way to find the optimal heap size is to run your application under simulated peak load with a large heap and monitor how much memory your application actually uses. If you find that your application uses only 180 MB of memory, for example, you might see performance benefit from reducing your heap size to 256 MB.

The java.lang.OutOfMemoryError error can occur in other, more complicated, conditions. One common cause of the error is when objects fill up the heap's permanent generation, which defaults to 64 MB. You can increase the value, for example, to 128 MB, by adding the following JVM argument to the Java and JVM Settings page of the ColdFusion Administrator:

-XX:MaxPermSize=128m.

Physical hardware memory is an important consideration when determining the optimal heap size. Setting the maximum heap size to a value that exceeds the amount of free physical memory causes severe performance degradation. For example, if you have only 512 MB of physical memory, do not set the maximum heap size to 512 MB. Because the operating system and other running applications use memory, much less than 512 MB of memory is available for the JVM process. it is important to have hardware that meets the requirements of your software application. For best results, run on server hardware with 1 GB or more of physical memory.

The Server Monitor Summary page monitors the JVM's memory usage. Use this information when determining the optimal heap size.

Variable memory usage

Configure client variable storage to use cookies or an RDBMS for best performance when using client variables; you do this on the Client Variables page of the ColdFusion Administrator.
Wherever possible, it is best to fully scope your variable names, especially when using the isdefined() }}function. For example, {{<cfif isdefined("variables.myvariable")> performs much better than <cfif isdefined("myvariable")>.

To monitor how variables use memory, view the reports in the Memory Usage of the Server Monitor.

Request handling

The Simultaneous Requests setting on the Settings page of the ColdFusion Administrator has the largest effect on how well an application performs under load. This setting dictates how many threads are used to simultaneously process incoming requests. For most applications, a good starting point for the optimal value for this setting is three per processor; you can set a dual processor computer to six simultaneous requests. To find the optimal value for this setting, test your application under load with different values until you find the value that provides the best performance under load. While you test your application, you can view the average response time on the Server Monitor Summary page and the reports in Statistics.

Caching

You can turn on the trusted-cache setting on the Caching page of the ColdFusion Administrator for production applications so that the server does not check the file system to see if the CFML source code changed since it was last compiled. This setting provides the benefit of minimizing system I/O, which has a major effect on performance. Set the template-cache size on the Caching page of the ColdFusion Administrator to be roughly equal to the number of ColdFusion templates that are normally used. To monitor how your settings affect performance, use the Template Cache Status in the Request Statistics section of the Server Monitor.
In addition, use one of the following methods to cache wherever possible in your application:

• The cfcache tag
• Database query caching. Database caching can provide significant performance and scalability improvements, and is accomplished with the cachedwithin and cachedafter attributes of database tags that support them, such as the cfquery tag.
• Storing data in persistent scopes such as session, making it available for longer than a single request.

Database response time

Wherever possible, it's best to allow database servers to handle data manipulation. Adding SQL code to handle this work is much more efficient than doing string manipulations or doing in-memory queries (query of queries). Additionally, stored procedures generally provide a higher level of performance than regular SQL queries. Converting queries in cfquery calls to stored procedures and using the cfstoredproc tag typically improves performance. To view database response time information, use the Database section of the Server Monitor (see Database).

Setting up Server Manager client

Server Manager is an AIR-based desktop application that allows you to centrally manage multiple ColdFusion servers from one location. From the Server Monitoring page, you can download and install the Server Manager client AIR application. 

For details about configuring the Server Manager client for ColdFusion server instances, see Working with Server Manager.

Configuring the Server monitoring settings

The monitoring server can be configured in one of the following ways:

• Use ColdFusion Administrator
• Manually edit neo-monitoring.xml and jetty.xml
• Use Admin API (servermonitoring.cfc)

Using the ColdFusion Administrator

Manually editing neo-monitoring.xml and jetty.xml

neo-monitoring.xml

Go to the following location:cf_root\lib (in the server configuration)orcf_root/WEB-INF/cfusion/lib (in the J2EE configuration).Modify the value to true in the following code:<var name='ismonitoringserverenabled'><boolean value='false'/></var>

Jetty.xml

Modify Jetty.xml only if you have to change the port or if your connection uses HTTPS protocol.Go to the following location:cf_root\lib (in the server configuration)orcf_root/WEB-INF/cfusion/lib (in the J2EE configuration).You can specify the following configurations in the XML file:

• Port
• MaxThreads
• Logging

For connections using HTTPS protocol

Using Admin APIs

To programmatically configure the Server Monitoring server, use the ServerMonitoring.cfc.
The following Administrator APIs are added in this release:

Troubleshooting scenarios

Multi-server monitoring

For multi-server monitoring, ensure that you specify the cross domain details in the crossdomain.xml in (CFRoot/MonitoringServer).

Someone changes port in XML

The exception does not appear in the ColdFusion Administrator. You verify the log.

Monitoring with SSL

You might encounter an error while starting Monitoring Server in SSL mode.
To resolve this known issue, add the following in the jvm.config:
"-Dcoldfusion.disablejsafe=true"

Updating the threadpool

You can update the threadpool in the jetty.xml.
Modify the threadpool in the Server Threadpool section of the XML file: