TechNote (Archived)

ColdFusion MX: Enabling metrics logging

ColdFusion MX offers multiple ways to generate runtime usage data. Performance Monitor integration, cfstat, and application logging all allow administrators to gather important statistics on a sites usage. One additional tool that is available with the ColdFusion MX Server configuration and ColdFusion MX J2EE with JRun configuration is JRun's metrics service. JRun's metrics service gathers and logs statistics on a number of important performance metrics including:

Metric	Description
listenTh	Threads listening for a new connection
idleTh	Threads waiting for a new request
delayTh	Threads waiting to run
busyTh	Threads currently running
totalTh	Total worker thread count
delayRq	Requests delayed due to high concurrency
droppedRq	Requests dropped
handledRq	Requests handled
handledMs	Milliseconds spent servicing requests not including any delay time (delayMs)
delayMs	Milliseconds spent in delay state
bytesIn	Bytes read from request
bytesOut	Bytes written to response
freeMemory	Kilobytes of free memory in the heap
totalMemory	Total Kilobytes in the heap (in use and free)
sessions	Current number of active J2EE sessions
sessionsInMem	Number of J2EE sessions in memory

Note: Metrics calculating thread statistics combine all HTTP request threads, thereby adding requests coming from the connector to those from the ColdFusion MX internal web server.

To enable JRun metrics logging, follow these steps:

Open the jrun.xml file for editing.
Server configuration:cf_root/runtime/servers/default/SERVER-INF/jrun.xml
J2EE with JRun configuration:jrun_root/servers/cfusion/SERVER-INF/jrun.xml

Verify the metrics service section is uncommented. The following are examples of what the XML should look like:

Server configuration:

 <!-- ================================================================== --><!-- This Service provides metrics information                          --><!-- ================================================================== --><service outputclass="coldfusion.server.jrun4.metrics.MetricsServiceAdapter" name="MetricsService"><attribute name="bindToJNDI">true</attribute></service>

J2EE with JRun configuration:

 <!-- ================================================================== --><!-- This Service provides metrics information                          --><!-- ================================================================== --><service outputclass="jrunx.metrics.MetricsService" name="MetricsService"><attribute name="bindToJNDI">true</attribute></service>

Change the metricsEnabled attribute to true:

 <service outputclass="jrunx.logger.LoggerService" name="LoggerService"><attribute name="errorEnabled">true</attribute><attribute name="warningEnabled">true</attribute><attribute name="infoEnabled">true</attribute><attribute name="debugEnabled">false</attribute><attribute name="metricsEnabled">true</attribute><attribute name="metricsLogFrequency">60</attribute>

Save the changes to the file.
Restart the ColdFusion Application server for the changes to take effect.

The metrics logger writes data to the server's log file at the interval specified in the metricsLogFrequency attribute. The default value is 60 seconds. For J2EE with JRun configurations, the metrics data will be written to the default-event.log. For Server configurations, the metrics data will be logged to the default-event.log (Windows) or cfserver.log and default-event.log (Unix).

The metricsFormat attribute controls the format of the data written to the server's logs and can contain literal text in combination with any or all of the available metrics variables (which are listed in the table above).

The following example shows how to configure themetricsFormat attributes for the metrics logger:

 <service outputclass="jrunx.logger.LoggerService" name="LoggerService"><attribute name="errorEnabled">true</attribute><attribute name="warningEnabled">true</attribute><attribute name="infoEnabled">true</attribute><attribute name="debugEnabled">false</attribute><attribute name="metricsEnabled">true</attribute><attribute name="metricsLogFrequency">10</attribute><attribute name="metricsFormat">Web threads (busy/total/idle): {busyTh}/{totalTh}/{idleTh} J2EE Sessions: {sessions} Total Memory={totalMemory} Free={freeMemory}</attribute>

The following example shows a log message generated with this format:

 02/14 16:11:53 metrics Web threads (busy/total/idle): 0/2/0 J2EE Sessions: 2 Total Memory=7252 Free=3103

Note: Due to Macromedia issue 46500, the JWS and web server metrics for ColdFusion MX Server configuration are combined when using the default metricsFormat in jrun.xml. To obtain accurate statistics, remove any instances of jrpp preceding a metric attribute.

The following indicates in red which text should be removed from the default jrun.xml (Server configuration only):

 <attribute name="metricsFormat">Web threads (busy/total): {jrpp.busyTh}/{jrpp.totalTh} Sessions: {sessions} Total Memory={totalMemory} Free={freeMemory}</attribute>

Since logging performance metrics adds additional load to the server as well as log files which increase in size, we do not recommend leaving the metrics service enabled for extended periods of time.