Prerequisite knowledge
Readers should have some experience with coding or managing a ColdFusion server.
User level
Required products
Adobe ColdFusion Enterprise Edition (2016 release) 8 (Download trial)


30 July 2007

Whether you're a CFML developer or a ColdFusion server administrator, you can find tremendous value from the new Adobe ColdFusion 8 Server Monitor. If you're a developer and the thought of a "monitor" makes you yawn, seeming to be the province of administrators, I'll show you in this article the many ways that the tool and some related functionality can be of great value to you, helping you make much better informed decisions about various coding practices. You no longer have an excuse to "just wing it" when using some feature, tag, or function in ColdFusion.
If you're an administrator responsible for a ColdFusion box, you may regard monitors as "idiot gauges" that you must constantly watch to get value from, or you may fear that monitoring is an inherently expensive operation that you can't afford in production. Again, I think you'll be quite surprised and impressed by the features available in ColdFusion 8, some of which have small (even nonexistent) overhead.
In this four-part article series, I'll split the discussion of the Monitor into features of interest during development, and features of interest in production. Of course, that's a somewhat arbitrary distinction: there's no inherent split in the functionality. Indeed, some of the features discussed in this article will certainly apply to production use, and vice versa. Consider it simply a different way to discover the many riches of this powerful new feature. I think you'll be surprised by what's possible.
Check out the other parts of the ColdFusion 8 server monitoring series:

Unlocking the "black box"

ColdFusion has long seemed a bit of a "black box," both to developers and administrators who've struggled at times to understand the cause of problems or even simply the impact of available choices, whether in CFML coding or in ColdFusion Server configuration. Finally, in ColdFusion 8, such folks can find most (if not all) the answers they seek by way of the new Server Monitor. Actually, the Server Monitor is more than just a monitor. It's both an interface and an administrative API (meaning you can write programs to access and respond to the monitoring data), and a handful of related functionality.
In fact, it's much more than just a tool that someone must watch incessantly to notice when graphs or charts change colors, reflecting some troublesome condition (though it does indeed do that). The Monitor includes features like alerts (triggered on a given condition, and responding automatically with a given action), as well as snapshots (an extensive logging of the current status of important factors that may help understand the cause of a problematic condition). The next two articles will introduce these various alternative features of the Server Monitor.
For most people, their first thought of the Monitor is the interface to view charts and graphs, so let's start by looking at that, and showing some fundamental uses of the interface, as well as an important point to note about various states of monitoring (which you can enable or not). Finally, I'll discuss some aspects of its use most suited to development activities.

Starting and using the Monitor

You can access the Monitor interface from the ColdFusion Administrator, using the option on the left navigation menu: Server Monitoring > Server Monitor > Launch Server Monitor. (You may notice a Multiserver Monitor option, which I'll discuss in part 3.) The Monitor interface is actually an Adobe Flex-based application, and you can launch it directly (without using the Admin console) by going to this URL in a browser (replace servername with your server's name): http://[servername]/CFIDE/administrator/monitor/launch-monitor.cfm.
The Server Monitor does, by default, require you to enter your Admin console password. If you defined multiple users, then different authorized users may have individual access to the Monitor.
The first page shown is the Overview or summary page, as shown in Figure 1. This shows a variety of charts and statistics about current execution of requests.
ColdFusion Server Monitor Overview page
Figure 1. ColdFusion Server Monitor Overview page
Note that the top two charts shown, Average Response Time and Requests Per Second, each have a drop-down option to change the displayed timeframe of information from All Data (reflecting all monitoring datapoints since the server started or the Monitor statistics were reset). You can set it to as little as the last minute to help you focus on the timeframe of data most important to you. The datapoints on the chart have pop-up information showing the exact time and value of a given point in the chart. (If you have not used the “start profiling” option, discussed in the next section, you will see no data on the first two charts, even if there are uses running requests on the server.)
The page also offers a Reports pane (below the 2 charts shown above), which shows current numerical values for various statistics (how many requests have had errors, have timed out, and so forth). Each report is also a drill down to more detail. If you double-click on a report name, such as Requests slower than nn seconds, you'll be taken to another screen showing a detailed drill-down for that report (typically showing a list of individual requests and their values), such as that in Figure 2.
A Report Summary Page (Requests slower than nn seconds)
Figure 2. A Report Summary Page (Requests slower than nn seconds)
Again, the report shown may have no data displayed, depending on the report you select and the “start” buttons selected. Also, in this example, I've modified the "slower than nn seconds" value on the report drill-down page to two seconds, simply to increase the display of data for these screen shots. You can select a value that's more important and meaningful for your data.
Note additionally that each line of that report is itself a drill-down. If you select a request line, you'll see additional detail about that particular request, including, in this case, tabs permitting you to view the value of variables for that request, including URL, session, Form, and CGI variables. If you have “start profiling” enabled (discussed in the next section), the bottom of the detail page shows the top 10 slowest tags or function calls in the request (see Figure 3).
A Report Detail Page (Slowest requests)
Figure 3. A Report Detail Page (Slowest requests)
You can return to the report drill-down page (listing all the requests for that given report) using the grid icon on the right side of the screen. Some reports will also have a chart icon next to the grid icon, offering charting of the data being displayed. You can also return to the starting Overview page using the Overview tab. Indeed, you may notice that when you select a drill-down report from the Overview page as in the steps above, you're actually taken to another section of the Monitor accessible through the Statistics tab, as shown at the top of the monitor display. That tab shows additional reports categorized under either “Request Statistics,” “Memory Usage,” “Database,” or “Errors.”

What it means to “Start Monitoring” (or not)

I've mentioned a couple of times already that some data will show up depending on whether you've enabled the start profiling option. Indeed, you may notice (on these screen shots and in your own display of the Monitor) that some of the charts or report data show no data (or a 0 value). While this could mean that there are no requests meeting the given criteria, it could also be that you simply have not enabled the monitoring option required to capture that data.
Notice at the top of the Monitor screen that there are three green buttons, each of which starts a particular form of monitoring. Even if you don't enable any of them, some of the reports and charts still track data. This is an important point to notice. In effect, these reports are "free" and incur no overhead to track. They reflect data to which ColdFusion inherently has access. There are many very useful reports in this class, including some data that are extremely useful and have never been available before. We'll focus on a couple types of data in this and the next article.
But many of the reports will not display meaningful data unless one of the "start" buttons is enabled. The options are:
  • Start Monitoring
  • Start Profiling
  • Start Memory Tacking
While the first option would seem key to any monitoring, again, that's not always the case. Many reports, including the Overview as shown in Figure 1, will reflect data even if none of the "start" buttons is enabled. According to Adobe, enabling both monitoring and profiling should incur only "minimal" overhead. The memory tracking option, however, can incur significant overhead and so should be used only for very short periods of time; perhaps not at all in production except when absolutely necessary. I'll introduce various reports and portions that rely on one or more of these options being enabled.

Useful monitoring for development

With some details of using the Monitor covered, I'll turn your attention now to details that could be of particular interest during development.
Tracking shared scope memory utilization
One of the most challenging problems in ColdFusion development has always been knowing how much memory is being used in shared scope variables, such as session, application, and server. Prior to ColdFusion 8, developers generally had little clue into the impact of their use of shared scope variables, especially when considered in the context of a large number of requests for the application. The Server Monitor reports this detail, either for particular requests, or for all active sessions, all active applications, and more.
Despite appearances, you do not need to start memory tracking to obtain much of this sort of data on shared scope variables. Note that even without any of the "start" options enabled, you can view all active sessions (and details including the name, value, and size) using the Statistics > Request Statistics > Active Sessions report (as in Figure 4). You can view application and server variables in use using Statistics > Memory Usage > Application Scope Memory Usage (as in Figure 5) and Server Scope Memory Usage, respectively. While each of these show a "size" value of 0, if you drill down into each, the detail page shown lists all the variables, their values, and the size—all even if none of the "start" options are enabled.
Active Sessions report
Figure 4. Active Sessions report
Application Scope Memory Usage report
Figure 5. Application Scope Memory Usage report
So how do these reports differ if you do enable one or more of the "start" buttons? With respect to these two reports, the "size" column will be populated if you enable both the "start monitoring" and "start memory tracking" features. While that's a marginal benefit for enabling the heavyweight "memory tracking" monitoring, that feature enables other very important information.
Track slowest tags or function calls
Perhaps one of the greatest benefits of enabling the ”start profiling” is that it allows you to track the slowest tags or function calls within a request. Recall the slowest requests detail page in Figure 3. With “start profiling” enabled, the section labeled “Top 10 Slowest Tags & Functions” will now be populated to show the tag or function name, the template path and line number from which it was invoked, and the time it took in milliseconds. If you select one of the lines showing that information, the “CFML Stack Trace” section below it will be populated with details about how this particular line was called from preceding templates in the request pipeline. All this information is incredibly helpful in development, when you're trying to understand the cost of various coding choices and to find bottlenecks.
Memory Usage Summary Report
Figure 6. Memory Usage Summary Report
Tracking largest variables in a request
When creating (and managing) ColdFusion applications, it can be vital to know how much memory is being used by each request—and to know in particular how that memory is being used among different scopes (variables, var, session, application, etc.) and by their type (query result, simple variable, etc.). Without this, it’s often a stab in the dark knowing where to begin tuning an application. One of the real gems of the Server Monitor is the Requests by Memory Usage report. Accessible with Request Statistics > Memory Usage > Requests by Memory Usage (figure 7), it lists the top requests (a number of your choosing) which exceed a given amount of memory (again, a number of your choosing). If you select one of the requests, you’re shown a detail page (figure 8) showing a breakdown of the top 10 largest variables in the request (by name, scope, type, template, and average/last size).
Requests by Memory Usage Report
Figure 7. Requests by Memory Usage Report
Requests Memory Usage Detail Report
Figure 8. Requests Memory Usage Detail Report
These reports require “start memory tracking”, which as stated above is the most expensive operation of all (in terms of overhead), and so should be used with caution. Still, even if enabled only briefly, and even for only your own requests made as a lone developer on your box, it can help you to understand the impact of your coding techniques. Of course, with load (whether simulated in development/test or by real load in production), you can obtain far more accurate and useful data about the impact of your choices.
Tracking JVM Memory Usage
Developers (and production admins) are often very interested in how ColdFusion is using the Java Virtual Machine memory that underlies ColdFusion. While various logging features could be enabled in ColdFusion to track this, or third-party tools could be used to visualize the use of memory, the Server Monitor now offers a graphical depiction of JVM memory usage. Accessible as Statistics > Memory Usage > Memory Usage Summary, it's shown in Figure 9:
Memory Usage Summary Report
Figure 9. Memory Usage Summary Report
Again, this is available even if none of the “start” buttons is enabled. If you enable memory tracking and monitoring, that same page also offers another chart (below that shown above) that tracks the amount of total memory used by each of the application, server, and session scopes.
Notice that there is a “Run GC” icon in the top left of this display. Clicking this will run the Java Virtual Machine garbage collector. This may be useful during development, but should not be relied upon as a solution to problems in production. Instead, the source of memory problems should be identified and resolved. Some of the other reports in the Server Monitor can assist with that effort.
Tracking cached queries
Until ColdFusion 8, we had no visibility into how many cached queries (CFQuery tags that use the CachedWithin or CachedAfter attributes) were being held in memory. But the Statistics > Database > Query Cache Status report now shows this information, and again it offers value even without any of the "start" buttons enabled, as the top portion of the chart (Figure 10) shows how many cached queries are in memory.
Query Cache Status Report
Figure 10. Query Cache Status Report
Note as well that the actual number of queries in cache is also depicted as a number at the top right of the chart, and at the top left is an indication of "Query Cache Hit Ratio." This percentage is very valuable, indicating how often requests for queries (using the caching attributes) did indeed find their query already stored in the cache. If that number remains low for an extended period with a production load, it means that the caching isn't providing much value, which could be for any number of reasons.
While that aggregate information is certainly better than when we had nothing, you probably will want to see still more detail, such as how often each cached query is requested (hit) versus executed (really queries the database). If you enable “start profiling,” you will find this information in the Statistics > Database > Cached Queries report (Figure 11), and if you double-click on a line in this report, you’ll be able to see the detail of each cached query, including its location (template and line number) and the SQL that’s cached, (Figure 12).
Cached Queries Report
Figure 11. Cached Queries Report
Cached Query Detail
Figure 12. Cached Query Detail
The monitor can even help you better understand ColdFusion operations. .For instance, did you know that multiple templates can share a single cached query, if the templates indicate use of caching and the CFQUERY attributes (most) are the same, and the SQL statement is identical, including line breaks? It's true, as discussed in the documentation on query caching. This Cached Queries report, however, will show only the first template that creates a given cached query result, even if other templates would reuse that cached result. If you click the refresh button (top right of the monitor) you can observe the hit count increasing on this page as you run other pages that share the same cached result.
There’s one gotcha related to the preceding Cached Query reports (not the Query Cache Status report): If you enable the “start” features after any query has already been cached, that cached query will not display on the report. To solve this problem, you can use the CFML tag with the action attribute of clear, cfobjectcache action="clear", which will clear the query cache so that future requests using the cached queries will display. Think twice about using this in production, if just to see this monitoring data. Clearing the cache will mean future requests must load the data from the database in order to repopulate the cache. The query cache will also be cleared when the cached queries expire or when the server is restarted next. If you'd like to know additionally the actual size of the cached queries (shown as zero in both of the preceding reports), you must enable "start memory tracking."
Tracking large, slow, and frequent queries
If you enable “start profiling” and “start monitoring,” you'll also enable the ability to track queries by their total execution time or their frequency of execution. If you add “start memory tracking,” you’ll also be able to track queries by their total memory used. These can help you find and focus on the queries you need to tune, which of course can be both useful and valuable if done during development.
You can reach the three reports, as Statistics > Memory Usage > Queries by Memory Usage (Figure 13), Statistics > Database > Slowest Queries (Figure 14), and Statistics > Database > Most Frequently Run Queries (Figure 15). In the first two of these screen shots, note that I've set the threshold value to zero to help produce additional data for this screen shot (which also means that the application shown is not a problematic one; it's just the one I was running at the time I took the screenshot).
Queries by Memory Usage report
Figure 13. Queries by Memory Usage report
Slowest Queries report
Figure 14. Slowest Queries report
Most Frequently Run Queries report
Figure 15. Most Frequently Run Queries report
For additional tuning techniques using the monitor, see the discussion of the Server Monitor in the ColdFusion documentation, as discussed in the final section below.
In this article, I've discussed just some of the many reports available in the ColdFusion 8 Server Monitor, with a focus on those most useful in development. In the future articles in this series, I'll focus first on more types of reports, especially ones useful for production, as well as the ability to abort troublesome requests. Then I'll discuss use of the multiserver monitor, as well as the alerts and snapshots features, and finally on miscellaneous aspects of using the monitor, including using the Admin API and various configuration settings for the monitor.

Where to go from here

Since online monitoring is a new feature in ColdFusion 8, the only substantial resources for learning more are the ColdFusion documentation. Since the Monitor is accessible from the ColdFusion Administrator (though it's technically separate from it), it's documented in the manual, Configuring and Administering ColdFusion, which like all the docs is also available online at the ColdFusion 8 LiveDocs site. Finally, note that there is also additional online help available within the Monitor, accessible using the question mark symbol (?) in the top right of the Monitor.
Check out the other parts of the ColdFusion 8 server monitoring series: