ColdFusion Article

ColdFusion 8 server monitoring – Part 4: Multiserver Monitor, Admin API monitoring, and more

Programmatic monitoring with the Admin API

Everything in this and the previous articles of this series has been about using the Flex-based Monitor and Multiserver Monitor interfaces to track what's been happening on the server(s) being monitored, and it's helpful that Adobe has provided those interfaces. They reflect best practices in rich Internet application (RIA) development and really make it easy to watch what's going on in your environment.

Inevitably, there may be something you want to see that's not shown there, or you may want to see it in a format that it's not (perhaps graphed), or you may want to view it for a different timeframe than is shown in the monitor, or you may want to log information to a file (something lacking in the CF8 Server Monitor).

The good news is that there's nothing that the ColdFusion 8 Server Monitor does that you can't programmatically create by way of the ColdFusion Administrative API, or Admin API. Introduced in ColdFusion 7, this set of ColdFusion components (CFCs) provide various forms of programmatic access to administrative functionality. What's new for ColdFusion 8 is that there is a new CFC devoted to server monitoring called servermonitoring.cfc. At this time, there's not much documentation at all on the Admin API in general, let alone this CFC in particular. Fortunately, there are ways to view the available methods and properties of this Admin API CFC.

The easiest way may be to use the built-in component explorer in ColdFusion by browsing the URL http://[server:port]/CFIDE/adminapi/servermonitoring.cfc, as in http://localhost:8500/CFIDE/adminapi/servermonitoring.cfc or http://www.somedomain.com/CFIDE/adminapi/servermonitoring.cfc. Note that you're pointing to the CFC within the adminapi directory under CFIDE (the same directory where the ColdFusion administrator is located).

When you browse a CFC this way, you will be prompted for the ColdFusion Server Administrator or RDS password (it doesn't seem to currently support the new multiple admin user feature in ColdFusion 8), and then shown high-level information about the CFC (see Figure 9).

Figure 9. Browsing the Admin API's servermonitoring.cfc

Here you can see first a long list of the many available methods, and then, paging down, you'll find information about each available method, including its expected arguments (if any) and what kind of information it returns. You can use these to invoke the component methods just as you would for any other CFC.

Here's a very simple example that displays counters of the kind of requests being made against the server:

<cfscript>
   // login to the Admin API

   admin=createobject("component","CFIDE.adminapi.administrator");


   // provide your admin password
   admin.login("adminpw");


   // create the server monitoring
   instancesmon = createobject("component","CFIDE.adminapi.servermonitoring");


</cfscript>

<cfdump var="#smon.getHitCountStats()#">

Note that any attempt to use the Admin API first requires that you programmatically log into the Administrator. The first two lines of code do that, creating an instance of the administrator CFC and then calling its login method, passing in your password. This example then creates an instance of the servermonitoring CFC and then invokes the getHitCountStats method, displaying its result (a structure) via cfdump. You can view more about the returned structure keys for a method by clicking on that methodname in the help offered in the component explorer, as shown in Figure 10.

Figure 10. Details of the information returned from getHitCountStats()

It's important to note that some of the methods, or some of the properties returned by the methods, may require that one or more of the monitoring features to be enabled. These were referred to in Part 1 and Part 2 of this article series as related to Start buttons in the Server Monitor (monitoring, profiling, and memory tracking), but note that these can also be enabled programmatically through either the startMonitoring or setMonitorSettings methods. This could be useful, as you could start a particular monitoring feature, get some needed data, and then turn it off. Just be aware that if you enable these settings, they remain enabled (just as the Start buttons do) until you disable them, as discussed in the final section here, "Start button settings remain enabled."

Along those lines, some of the documentation discussing which monitoring feature must be "started" for a given API method or interface feature is not always complete or correct. For instance, in Figure 10, it says for the getRealTimeStats function that "monitoring must be turned on for the function to work," but it does indeed work and return some useful data regardless; it's just that some of the values will be zero (of course, they can also be zero even if monitoring is enabled, simply because they have no value).

I'll leave it to you to explore on your own the other available monitoring API methods.

Page 4 of 6

Previous Page

Next Page