How to setup FacesTrace

March 25, 2011

If you’ve ever been caught trying to debug a Java Server Faces (JSF) 1.0 or 1.1 problem you know that you either get the “stack trace from hell” or too little output – in either case you don’t have what you need to troubleshoot. The problems that produce no helpful output (the kind you usually use the <h:messages></h:messages> tag to output to your JSP) are the ones that can be especially tricky. Since JSF gives no indication as to what actually went wrong, you’re stuck with various and tedious debugging techniques to troubleshoot a problem that is originating within the JSF life cycle. Luckily, there is a handy tool to help see inside the black box that is the JSF life cycle. FacesTrace is a very simple tool that visualizes the steps in the JSF life cycle, which ones passed or failed, and how long each step took to execute.

I believe that FacesTrace used to be a stand-alone tool but now is part of the PrimeFaces framework. I could not find a download of just FacesTrace anywhere on that site though, which was very confusing. I downloaded the PrimeFaces framework but it was devoid of anything specifically related to FacesTrace. I did find that you can download the facestrace.jar from SourceForge, which is where I suggest you get it from. The version this blog is based on is 1.0.1.

David Geary and Cay Horstmann recommend FacesTrace in their book Core JavaServer Faces 2nd Edition, but they’re missing a few steps in the setup. Even so, the full setup is dead simple. I couldn’t find that anyone else had documented it, so I’ve done that here. The steps are below. I’m assuming you’re familiar with a JSF application and you just want to use FacesTrace in it.

4. Add the FacesTrace trace tag in an appropriate place on your JSP page:

<ft:trace></ft:trace>

When you run your app and navigate to the page where you enabled FacesTrace you’ll see something like the image below:

The green boxes under the “Request Lifecycle” header represent the major steps in JSF’s lifecycle. Notice that each box contains the name of the lifecycle step and how long it took to execute. Boxes are green if the step succeeded and red if they did not.

The blue headers are clickable and will expand when clicked on. Another cool feature is under the “Component Tree” heading. Under this you can explore the JSF component model for the page, complete with component id’s and values. An example is below.

The rest of the interface is self-explanatory. I haven’t used FacesTrace much yet, but it’s worth adding to your app just in case you need it. If nothing else, playing around with it for some time will enhance your understanding of JSF!

As always, if I’ve been unclear, left something out, or you have some other question, please leave a comment on this post and I will respond soon.