One of the principal benefits of getting Helix to OS X is that it provides us with a better set of tools for determining the cause of a Helix crash than we've ever had before. When an OS X native Helix application crashes, a file is created that contains detailed information that can help us isolate the source of the crash. However, Apple’s built-in Crash Reporter (the window that comes up after a crash, asking you to describe the events preceeding the crash) only sends the report to Apple and Apple does not forward them to us.
The purpose of this article is to explain how you can retrieve these crash logs and submit them to us in a way that allows us to efficiently deal with them. (Hint: it's not via email.)
As we identify bugs and provide explanations, workarounds, and/or fixes, we update our knowledgebase. You can see the current state of Helix 6 bugs by checking the Known Issues/Helix 6 Specific section of the knowledgebase.
Section 2.3 Bug Reports
If we are to continue to improve the product and meet the needs of our customers, we need to know when you experience problems. Please contact technical support using one of the methods listed above when you discover something you believe to be a bug in Helix.
2.3.1 OS X Crash Logs
OS X provides enhanced tools for determining the cause of an application crash. If an OS X native Helix application crashes, a file is created in the User’s /Library/Logs/CrashReporter/ directory. This file contains detailed information that can help us isolate the source of the crash. If you experience crashes with any OS X native Helix application, please use a current copy of Helix Client to visit our Helix Technical Support Server at techdb.qsatoolworks.com (log in with user name “Guest” — no password is required) and use the “Send Document” command to send the crash log to us. In the “Tech Support Ref#” field, enter your customer number, and enter any important information in the “Notes” field.
Please note that in those notes, we do not ask you to submit crash logs via email. Why not? Primarily because it is inefficient. If you email them to us, the person receiving the email must then turn around and load the crash log into the support database. At this point, the entry goes in without your customer number (unless you happened to provide it) and we have lost the ability to contact the person who the crash actually affects. By submitting the crash log yourself, you enable us to efficently contact you when we need further information or we have a fix for the bug to distribute.
When an OS X native Helix application crashes, a file is created in the User’s /Library/Logs/CrashReporter/ directory. To see this file, open a Finder window. Under the Go menu, select "Home" and then follow this path:
Feel free to read the crash log, but be very careful not to change anything in it. Double clicking it typically opens the Console application, but you can drag it onto any text editor. The important thing is that you have found the information we need to understand why your Helix OS X application is crashing.
Once you've found the crash log, drag it out to the desktop (or some other place that will make it easy to find). Crash logs accumulate data, so if you don't remove it from the CrashReporter folder, later crashes will be added onto this file, and if you sent that file in later, we'll end up with redundant data. And that will just slow us down, so please: after you've sent us the file, delete it so you don't accidentally send it to us again.
With crash log in hand, you are ready to log into our database and send it to us. To log in, you must have a current copy of Helix Client. If you don't have it already, you can download it from our downloads page, or install it from a CD.
After launching Helix Client, there are two ways you can log in:
- Open a saved structure: In the "Things You Might Need" folder (it is found inside the Helix folder you created when you installed Helix 6) there should be a file named "Helix User Services Structure." Open it with Helix Client: Drag and Drop it onto the Client application or choose Open from the Helix Client's File menu and select it. (If you are a participant in our Friday afternoon live chats, you can use that saved structure too.)
- Visit the collection: Launch Helix Client, select Visit from the File menu, enter techdb.qsatoolworks.com in the Locate Server field, and click the Find button. When the collection is found, click the Visit button.
Once you have contacted the Server (this may take a few seconds) you will be presented with the user log in dialog. Your user name is guest.
Under the Guest Menu there is a Documents hierarchical menu. In that menu is the Send Document view. This is the form you use to send the crash log to us. In the Tech Support Ref# field, enter your customer number, and enter any important information in the Notes field. Then, when you tab (or click) into the Document field the Send Document button activates. Clicking it opens a dialog that you use to specify the document to send.
Navigate to the crash log and click the Copy File button. Helix will transfer the file to our collection and return you to the Send Document view, with your document showing in the Document field.
That is all there is to it! This seems to confuse some people, as they seem to think they must now ‘do something’ to finish the task. You've already done it. The document is now on our server. If you want to send another document use the Clear button to clear the form. Otherwise, just close the form, because the work is done.
Our staff reviews the submitted documents and searches for patterns that can be used to isolate and fix the bugs. We tend to focus on the bugs that are reported by the most people, which is why submitting crash logs this way is the best way to get your bug fixed.
If your bug is affecting a mission critical application, feel free to follow up with an email to our support department, letting us know about the document you uploaded. We'll take a quick look and let you know if we have any insight into your particular issue.
But please understand: fixing bugs is typically a task that is measured in weeks, not days or hours. The chances of us being able to find the bug, fix the bug, test the fix, build a new version of Helix, and distribute that fix in time for your next business day are non-existent. This is the harsh reality of most of the bugs we have seen.
CrashReporter is a debugging facility in Mac OS X that logs information about all programs that crash. For more information about crash logs and CrashReporter, check out this technote from Apple.