ColdFusion 8: Server Monitor API

coldfusion (This post is more than 2 years old.)

In an earlier post I talked a bit about how the Admin API has been updated in ColdFusion 8. For folks who don't know what this is - it is a way to get into the internals of ColdFusion directly from CFML. It requires the ColdFusion Admin password, which may be a negative for some, but if you have access to it, you can do quite a bit. As an example, I could build an installer for BlogCFC that would prompt the user for the CF Admin password and then handle creating the datasource for you. So it's cool. We know that. But how cool is it in ColdFusion 8?

Well you know that server monitor that ships with the product? If you haven't seen it, you need to spend some time with it. I spent 5 minutes running it with BlogCFC and saw immediate, serious performance issues I was able to correct. 5 minutes to improve my application in a dramatic way is worth the cost of ColdFusion 8 right there. But did you know that 100% of what you see in the Flex application is available to you via code?

Added to the Admin API is a new CFC, the Server Monitoring CFC. This CFC gives you access to everything you see in the Flex app, and maybe a bit more. Now it is important to note that each method has different requirements for server monitoring. Some require that memory tracking is turned on. Some require nothing. Some return data but will return more data if memory tracking is on. You should read the docs carefully to see what each method requires.

What follows is a short list of some of what is available...

Get Active Session Count

This lets you get the total number of active sessions for the server - or you can supply a ColdFusion Application name and get the number just for that application.

Get Average Response Time

This is a great metric. It tells you - on average - how quickly your templates are responding.

Get Heartbeat

This returns a structure of general information. This includes a variety of items like server up time, average request time, current requests, etc.

Get Memory Utilization Summary

As you can guess - this returns information about your memory usage. It tells you how much data your Application, Server, and Session scope data is using.

Get Hit Count Stats

Now this one is truly cool. Along with telling you how many normal template hits you have - it can tell you the number of web service hits - the number of Flash Remoting hits - even the number of direct HTTP hits to your CFCs.

Get Logged In User Count

Returns the number of users logged in via CFLOGINUSER.

Get All Application Scope Memory Used

This returns all your applications and the amount of RAM they are using. Have a machine that is running a bit slow? Run this and it will tell you if one application in particular is being a bad boy. You can follow it up with getApplicationScopeMemoryUsed which returns specific data about one particular application.

Cool stuff, eh? It is important to note that using these features will have an impact on your server performance. I had a demo online, but I could really tell the impact of the monitoring so I turned it off. But if you want to see the code I used (with a different Admin password of course, I trust some of you guys... ;), look here:

<cfinvoke component="cfide.adminapi.administrator" method="login" adminPassword="mypasswordcanbeatupyourpassword">

<cfinvoke component="cfide.adminapi.servermonitoring" method="getActiveSessionCount" returnVariable="result">

Total session count = <cfdump var="#result#">

<p>

<cfinvoke component="cfide.adminapi.servermonitoring" method="getActiveSessionCount" returnVariable="result" cfapplicationname="lighthousepro">

For app lighthousepro = <cfdump var="#result#">

<p>

<cfinvoke component="cfide.adminapi.servermonitoring" method="getAverageResponseTime" returnVariable="result">

<cfoutput>Average response time is #result#</cfoutput>

<p>

<cfinvoke component="cfide.adminapi.servermonitoring" method="getHeartbeat" returnVariable="result"> <cfdump var="#result#" label="Heart Beat">

<p>

<cfinvoke component="cfide.adminapi.servermonitoring" method="getMemoryUtilizationSummary" returnVariable="result"> <cfdump var="#result#" label="Memory Utilization">

<p>

<cfinvoke component="cfide.adminapi.servermonitoring" method="getHitCountStats" returnVariable="result"> <cfdump var="#result#" label="Hit Count Stats">

<p>

<cfinvoke component="cfide.adminapi.servermonitoring" method="getLoggedInUserCount" returnVariable="result">

Logged in users = <cfdump var="#result#">

<p>

Hire Me!

I'm currently looking for my next role in developer evangelism and advocacy. I have a long history of helping companies work with developers and love to write, create demos, and present at conferences. You can find my resume to learn more and drop me an email (raymondcamden@gmail.com) to reach out.

Support this Content!

If you like this content, please consider supporting me. You can become a Patron, visit my Amazon wishlist, or buy me a coffee! Any support helps!

Want to get a copy of every new post? Use the form below to sign up for my newsletter.

Archived Comments

Comment 1 by Gary Fenton posted on 6/15/2007 at 3:31 PM

Thanks Ray. It gave me an idea that if the site is really busy, e.g. average response time is GT 2000 ms then it could automatically disable some processor intensive functions of the site with a "sorry, we're really busy etc" type of message for the user. That way most users can continue to use the site without it being slowed down further by the more intensive requests.

But then I read the part where you said that with monitoring switched on you noticed it slowed the site down. Doh. Perhaps there's a way to only monitor just 1 statistic instead of having everything being monitored?

Do you know if the API lets you access stats from a cluster or does it limit you to just one server's stats at a time? e.g. average response time for the cluster, the number of sessions over the entire cluster, etc.

Comment 2 by Raymond Camden posted on 6/15/2007 at 4:40 PM

Gary, as far as I can see, it is just for one machine.

Comment 3 by Rob Brooks-Bilson posted on 6/15/2007 at 5:23 PM

Gary,

Since CF 8 Enterprise supports monitoring multiple machines, you would think that the ability to do that via the API might be included as well, but as Ray mentions, so far, it looks like you can only monitor the server where the CFC lives.

A little more digging (or comment from the CF team) might be in order here.

Comment 4 by Jay McConathy posted on 6/15/2007 at 8:53 PM

I found this info from Charlie Arehart pretty useful as well.

http://carehart.org/blog/cl...

Jay

Comment 5 by Raymond Camden posted on 6/15/2007 at 9:01 PM

I posted a comment there, but I have to say that I do not know if it is entirely safe to turn on profiling/monitoring. Again, this is JUST my personal experience - but I felt it had too much of an impact on my machine here to leave it on. I'd urge folks to carefully monitor their site (heh, monitor the monitor) if they turn on these features.

Comment 6 by Sean Corfield posted on 6/15/2007 at 10:49 PM

The multiserver monitor exposes some basic information about each server so clearly that information *is* available through the API. Since the API is, by definition, exposed remotely so that the Flex app works, it *must* be possible to get all of that information for a remote server, using a SOAP web service or via Flex Remoting using your own Flex application. Or AIR application. You would need to deal with crossdomain.xml (for Flex Remoting, not for AIR) but it should be possible to pull all this information from any server.

Comment 7 by Raymond Camden posted on 6/15/2007 at 11:32 PM

But have you _seen_ the API? Granted there are a lot of methods in servermonitoring.cfc, but none of them seem to be related to this. (As far as I can tell.)

Comment 8 by Rob Brooks-Bilson posted on 6/16/2007 at 12:17 AM

That's what I'm saying - it should be possible because CF is already doing it. It's just a question of if it's documented, and not protected somehow.

Comment 9 by Sean Corfield posted on 6/16/2007 at 3:05 AM

@Ray, I'm a bit confused. What is it you think is not possible using the servermonitoring.cfc API? Every single method is remote. Is it just the issue that you need to login to the administrator *locally* before you can use (some of) the servermonitoring remote API?

Comment 10 by Raymond Camden posted on 6/16/2007 at 3:14 AM

This is more Rob than me. Rob wanted to know (and Rob, correct me if I'm wrong), if from Machine A, can I use the server monitor to inspect Machine B, like you can from the CF Admin on Machine A.

In other words - the CFC currently seems to show everything you get in the Server Monitor. Great.

But where is the API for the Multiserver Monitor?

Comment 11 by Raymond Camden posted on 6/16/2007 at 3:17 AM

Hmm. Hey Rob - correct me if I'm wrong - but I think the multiserver monitor is simply doing the same calls to other boxes that the SM does to the current server. Which I believe is what Sean was saying. So really, the MultiServer monitor is nothing more than a collection of links to other boxes, with a bit of info shown visually.

So in theory, we don't need another API at all, we just point to the other box.

Again - if I'm reading you right.

Comment 12 by Mark Ireland posted on 2/20/2008 at 6:23 AM

So getting the ActiveSessionCount for one application by name is like this?

<cfinvoke component="cfide.adminapi.servermonitoring" method="getActiveSessionCount" returnVariable="result"
name="myApp1">

Total session count = <cfdump var="#result#">

Comment 13 by Raymond Camden posted on 2/20/2008 at 7:02 AM

Yep. Check the docs (view the CFC) to confirm.

Comment 14 by Mark posted on 2/20/2008 at 4:51 PM

What docs?

Isnt this undocumented?

Isnt this cfc encrypted?

How would I do this?

Comment 15 by Raymond Camden posted on 2/20/2008 at 7:16 PM

You do know that you cna open a CFC in your browser and it will self-document, right? Try it. You need the Admin/RDS password, but you will see a nicely documented page for the CFC.

Comment 16 by Mark Ireland posted on 2/21/2008 at 5:05 AM

I tried this and got a timeout.

Can I point to your blog.cfc and see this working?

Comment 17 by Raymond Camden posted on 2/21/2008 at 6:56 AM

You mean my blog.cfc here? No. I can't turn off the passwords. I can say I've seen issues with the timeout before -o n Macs. Try reloading the page after the timeout. I bet it will work then.

Comment 18 by Mark Ireland posted on 2/21/2008 at 12:24 PM

Is it as simple as

http://www.mysite.com/cfc/m...

Do I add my password to this url?

Comment 19 by Raymond Camden posted on 2/21/2008 at 4:52 PM

No. CF will prompt you for the password.

Comment 20 by cfdev posted on 4/2/2008 at 5:56 PM

I turned Monitoring on and thought that the server was going to keep collecting data after I logged out. But when I logged back to Administrator and went to Server Monitor, it only showed data starting from the present.

How do I make Server Monitor display data for, say, two weeks, without having to keep my browser open? Is it even possible? :(

Comment 21 by Raymond Camden posted on 4/2/2008 at 6:08 PM

I think you mean just the dashboard. I know I see older data in the other screens. I just hit my SM locally and I haven't hit in weeks, but it had yesterdays data in it - again though - in the sub pages, not hte dashboard.

Comment 22 by Andy Matthews posted on 6/10/2008 at 7:29 PM

Quick question about the getHeartBeat method. It returns a structure containing a key called serveruptime. The docs just say "SERVERUPTIME -- Server's start time". I just ran this on my machine locally (restarted last night) and got the value "65877267". Is this in milliseconds? I'm guessing it is because that amounts to 18 hours which is roughly equivalent to when I restarted my local machine. I'd just like confirmation.

Comment 23 by Raymond Camden posted on 6/10/2008 at 11:04 PM

You got me there. I'd log a bug report with Adobe to edit the CFC to make this more clear. But I'm sure your right about it being MS.

Comment 24 by Nkonye posted on 8/22/2008 at 1:18 PM

I've been experimenting with servermonitoring.cfc and I was wondering if you knew of any method of getting this information for separate machines.

Comment 25 by Raymond Camden posted on 8/22/2008 at 3:05 PM

The only way I think you can do this if you build a CFC to expose the methods of the SM to other machines. So your code on machine A would use web services to hit your new on machine B, which in turn would talk to the SM API on that machine.