QuackFuzed [ Ramblings of a Con..ColdFuzed Mind ]

Integrating Mura CMS and Hoth Exception Tracker for ColdFusion

Posted on June 7, 2011 at 11:56 AM in ColdFusion

A few months back Aaron Greenlee released his Hoth project, which is an exception tracking/reporting application for CFML. I've been wanting to find time (let me know if you've ever found time) to take a look at it, but haven't had a chance. Until now, that is.

After taking some time to read up on Hoth as well as how Mura handles exceptions it encounters, I set off to integrate Hoth into Mura. Now that I've done it once, I wanted to document it so that a) it can serve as a refresher course so that I can do it much more quickly the next time, and b) hopefully someone out there in the community at large can benefit from my experience with it and save themselves time as well.

I am assuming that you already have a Mura install running and powering a site with the SiteID 'mysite', and that you have already downloaded Hoth, so let's get to setting them up to play together.

Setup Hoth Mapping

Mura provides a place for you to place your custom setup code, which would ordinarily be in Application.cfc. This place is located at {Mura Install}/config/cfapplication.cfm. In my example, the full path to this file is

1. /home/matt/www/websites/mura/config/cfapplication.cfm

My Hoth install is located at

1. /home/matt/www/frameworks/hoth

Open up Mura's cfapplication.cfm and create the mapping to Hoth.

1. <cfscript>
2. this.mappings['/Hoth'] = "/home/matt/www/frameworks/hoth";
3. </cfscript>

Config Hoth

Next we want to config Hoth so that it knows where to place log files, where to send emails, our application name, etc. To do this, we are going to utilize Mura's onSiteRequestStart() event handler. Open up

1. {Mura Install}/mysite/includes/eventHandler.cfc

and add the following code:

1. <cfscript>
2. function onSiteRequestStart(
4. )
5. {
6. var HothConfig = "";
7. if ( structKeyExists(application,"HothTracker") == false )
8. {
9. HothConfig = new Hoth.config.HothConfig();
10. HothConfig.setApplicationName(application.applicationName);
11. HothConfig.setLogPath("/Hoth/logs");
12. HothConfig.setEmailNewExceptions(true);
13. HothConfig.setEmailNewExceptionsTo("rutroh@me.com");
14. HothConfig.setEmailNewExceptionsFrom("noreply@me.com");
15. HothConfig.setEmailExceptionsAsHTML(false);
16. HothConfig.setHothReportURL("http://" & cgi.server_name & "/hoth-error-report/");
17. application.HothConfig = HothConfig;
18. application.HothTracker = new Hoth.HothTracker(application.HothConfig);
19. }
20. }
21. </cfscript>

A couple of settings of note here:

• setEmailExceptionsAsHTML()
  If you would prefer to have a dump of the entire exception emailed to you, set this to true.
• setHothReportURL()
  This setting defines the URL where you will view exception reports. In this example we will be creating a protected Mura page to view them (keep reading).

Setup Mura to Catch Exceptions

First thing you'll want to do is to turn off Mura's debug mode. Open up

1. {Mura Install}/config/settings.ini.cfm

and set 'debuggingenabled' to false. Failure to do so will result in some exceptions being caught and others bubbling up to the view.

Create a Friendly Error Message

Next, we'll create a new Mura page to display a nice, clean message to users. We will also have it properly set a 500 response header to let the browser know that an error occurred. (This is actually a two-step process.)

Step 1: Create {Mura Install}/mysite/includes/display_objects/custom/dsp_error.cfm and add the following code:

1. <cfheader statuscode="500" statustext="Internal Server Error" />
2. <cfoutput>
3. <h1>Error Encountered</h1>
4. We apologize for the inconvenience, but an unexpected error was encountered. The webmaster has been notified.
5. </cfoutput>

Step 2: Create a Mura page named 'Error' and set the body as follows:

1. [mura]dspInclude('display_objects/custom/dsp_error.cfm')[/mura]

Note: Be sure to UNcheck "Include in Site Navigation" (on the "Basic" tab) and then select "Do Not Inherit Cascade" (on the "Content Objects" tab). The former is so people don't browse to your error page, while the latter keeps any problem content objects from causing an infinite loop on redirect should one of them be the cause of the exception being thrown.

Tell Mura How to Handle Exceptions

Now we are ready to tell Mura to pass any exceptions off to Hoth for tracking. We will take advantage of Mura's onSiteError() and onGlobalError() methods for this task. Open up

1. {Mura Install}/mysite/includes/eventHandler.cfc

again, and paste the following code in:

1. <cfscript>
2. public any function onSiteError(
3. required any event
5. )
6. {
7. // track the error, then redirect to error page
8. application.HothTracker.track(arguments.event.getValue("exception"));
9. location(url="/error/",addtoken=false);
10. }
11. public any function onGlobalError(
12. required any event
14. )
15. {
16. // track the error, then redirect to error page
17. application.HothTracker.track(arguments.event.getValue("exception"));
18. location(url="/error/",addtoken=false);
19. }
20. </cfscript>

We've done two things here: First, we are passing the exception off to Hoth for logging. Second, we are redirecting the browser to our friendly error message page that we created earlier.

Note: The value of "/error/" assumes that you have Mura configured to not require the SiteID or index.cfm. If you need one or both of those for your installation, be sure to include them.

Viewing Exception Reports

We're almost done, I promise. But it kinda wouldn't make a hell of a lot of sense to trap and record exceptions if we can't ever view the exception details! For this, we're going to create another page in Mura that displays a custom display template (Step 3/4, below). But first we need the HothReportUI.cfc.

Step 1: Copy the HothReportUI.cfc from the Hoth download (/examples/ColdFusion/HothReportUI.cfc) and place it into your directory structure in a "hard-to-find" location. For my example, I renamed the file to a UUID and placed it in the following path:

1. {Mura Install}/mysite/coffee/warms/the/belly/G98783C2-A76D-4F92-P067D979CA72EBD7.cfc

Step 2: Tell the ReportUI object where to find the Hoth config. On or about Line 25 of the HothReportUI file you placed into your application, replace this line

1. variables.ApplicationsHothConfig = new Hoth.config.HothConfig();

with this one:

1. variables.ApplicationsHothConfig = application.HothConfig;

Step 3: Create {Mura Install}/mysite/includes/display_objects/custom/dsp_hothreports.cfm. In this file, paste the code from the /views/report.html file in the Hoth download package. (You will want to strip out the <html>, <head>, and <body> tags, leaving only the styling, html markup, and JavaScript.)

IMPORTANT: You MUST update the following line to point to the location of the report CFC you setup a moment ago.

1. var HOTH_REPORT_URI = '${HOTH_REPORT_URL}';

We want to provide some security for this page, so include the following at the very top of the file:

1. <cfif $.currentUser().isInGroup("Admin") NEQ TRUE>
2. <cflocation url="/" addtoken="false" />
3. </cfif>

Here we're simply asking Mura to make sure that the user requesting the page is logged in as an Administrator before displaying the page. If not, we're sending the user to the site home page.

Step 4: Create a page named 'Hoth Error Report' in Mura that includes the custom display template we just created. Like the friendly error message page above, UNcheck "Include in Site Navigation" and select "Do Not Inherit Cascade". Then set the body content with the following:

1. [mura]dspInclude('display_objects/custom/dsp_hothreports.cfm')[/mura]

Track and View

WHEW! Now you're ready to fire up Mura and have your exceptions tracked by Hoth. To give it a whirl, do something silly in a page, like <cfoutput>#</cfoutput>. You should be presented with a friendly error page while an email report is sent to you.

Happy erroring!

Comments

(Comment Moderation is enabled. Your comment will not appear until approved.)

On 8/2/11 at 8:49 PM, Michael Evangelista said:

I've been wanting to check out Hoth, and add my own cfmail error handling to Mura for quite a while. This looks like just the thing for both, I'll give it a shot, thanks!

On 8/2/11 at 9:59 PM, Matt Quackenbush said:

@ Michael - Hope it helps! I keep meaning to come back and do a follow-up post, as we've had to tweak a couple of things, but Hoth is definitely a nice addition to Mura. :-)

(Namely, we've added a check for local development environment and just dump the exception rather than wasting time by sending it to Hoth. We've also added a check to make sure that the page causing the exception is not the friendly error message page, since you end up in an endless redirect loop if it is.)

On 8/3/11 at 3:33 AM, Michael Evangelista said:

This worked great! I got hung up a little on the reporting display page for Hoth, because of where I put the files within my mura site. (i wanted to put the entire Hoth folder inside the "display_objects/custom/" directory so it could be bundled along with a site on export, but Mura didn't let me get direct access to the .cfc from there.) Instead, I have it in [mura root]/requirements/ which seems to work just fine, once i got the paths sorted out. Very nice, thanks for detailing the steps so well. (p.s. i've subscribed to comments on this post, so if you get a chance to update with your newest tweaks, be sure to add a comment!)

On 10/22/11 at 7:06 PM, Greg Moser said:

@Matt,

First and foremost, great post. I liked it so much in fact I actually just hammered out a quick Mura plugin for Hoth that can be found here (https://github.com/gregmoser/MuraHoth). Hopefully you might find it useful going forward. I'd be interested to hear any feedback you might have as well.

On 2/9/12 at 1:41 AM, Mike Schierberl said:

Did you ever make any progress or get a response on the debugging bubbling up to the view? I was scratching my head on this for way too long earlier today. It seems like errors that occur within the body should fire the error events.

On 2/9/12 at 6:12 AM, Matt Quackenbush said:

@ Mike - There were a number of bugs that were fixed surrounding the error handling in Mura, but I honestly don't recall whether that was one of them. I would make sure you have a recent Mura version (5.6.x?) and, if the issue still exists, post to that forum thread and hope you get a reply. :-)

Sorry I don't have a better answer for you. It has been a really long time since I've looked at this stuff, and my memory isn't the best. :-(

On 8/24/12 at 11:42 PM, Justin said:

I've search all over the web, and have not found a way to temporarily turn off HOTH. I would like to see the raw error if I am the person that creates the error. In my other application I simply ignored error handling based on my session info.

Can this be done easily with Hoth?

On 8/29/12 at 4:42 PM, Matt Quackenbush said:

@ Justin - Temporarily disabling Hoth would be done just like you'd disable any other error handling. For example, wrap the call to HothTracker.track() with an if() that checks to see if it's your IP, or if the server IP is 127.0.0.1. If it is, just dump the error and abort. Otherwise, send it over to Hoth for handling.

On 9/12/12 at 7:22 PM, Justin said:

@Matt, worked like a charm. I have a situation where I need to capture the SESSION data, I've tried altering the HothTracker.cfc but doesn't seem to add it anywhere. Have you came across this and if so do you have a simple work around?

On 10/31/12 at 6:43 PM, Matt Quackenbush said:

@ Justin - Sorry I somehow missed your comment coming in. I've never had a need for session info, so I'm not sure on that one. I would recommend posting to the Hoth Google Groups list. Hopefully Aaron (or someone else) will have already done what you're needing to do. HTH!

[Add Comment]