Diagnostic Reports

Quite often, if you contact the BitPerfect support line to report an issue with BitPerfect, we will ask you to send us your Console Log, a Process Sample, a Crash Report, or the Device Info report.  If you are not au courant with the under-the-hood workings of a Mac, you may be confused as to what we mean.  This brief note is to help you out.  It was originally written for users running Mountain Lion (OS/X 10.8), and may therefore be slightly different for High Sierra (10.13), Sierra (10.12), El Capitan (10.11), Yosemite (10.10), Mavericks (10.9), Lion (10.7) or Snow Leopard (10.6) users.  In particular, the Console App underwent significant modifications with the introduction of macOS Sierra (10.12).


Console Log


Before generating a Console Log, it is always best to quit BitPerfect, unless we have instructed you to do otherwise.

The Console is a Mac system application.  You will find the Console App in Finder under "Applications|Utilities".  Alternatively, you can search for it using Spotlight.  Run the Console App.  You should see two panes in the Console window - a narrower grey pane (the navigation pane) on the left, and the larger main data window on the right.  If you do not see the navigation pane on the left, click on the icon labelled "Show Log List" and it will appear.

With versions of OSX up to and including El Capitan, please do as follows:  In the navigation pane, look for System Log Queries, then immediately below it click on All Messages.  Next, click on the icon labelled Clear Display.  Now launch BitPerfect and use it to play music, or to perform some other function as instructed by BitPerfect Support.  You should see various messages appearing from BitPerfect.   During this time, please refrain from doing anything that would interrupt or in any way affect playback.  When you are ready to do so, typically after a minimum of 15-20 minutes of playback (or as instructed by BitPerfect Support), you can send the Console Log to the BitPerfect Support Line by first clicking anywhere in the main data window, then choosing "Edit|Select All" then "File|Save Selection As ..." from the Main Menu, and attach the resultant file into an e-mail.  It really is preferable to send the Console Log as an attached file, rather than pasting it into the e-mail, as this enables us to view it using the Console App, which makes our job a lot easier :)

With the new macOS Sierra, please do as follows:  In the navigation pane look for Reports, then in the list below it click on system.log.   Next, click on the icon labelled Clear.  Now launch BitPerfect and use it to play music, or to perform some other function as instructed by BitPerfect Support.  You should see various messages appearing from BitPerfect.   During this time, please refrain from doing anything that would interrupt or in any way affect playback.  When you are ready to do so, typically after a minimum of 15-20 minutes of playback (or as instructed by BitPerfect Support), you can send the Console Log to the BitPerfect Support Line by right-clicking on "system.log" and selecting "Reveal In Finder".  This will open a Finder window showing the system.log file.  Attach that file to an e-mail replying to this message.

With the initial release of OS X 10.10 (Yosemite), the Console Log is unfortunately being filled with a flood of messages from AppleEvents.  This, in effect, is like a Denial-of-Service attack on the Console App, and renders it close to useless for diagnostic purposes.  We are seriously hoping that Apple will find a fix for this in an early Yosemite update. Until they do, we have developed a temporary fix, which is described in a special update below.


Process Sample, and Crash Report


If BitPerfect stops functioning, it may either have crashed or hung (we are assuming here that you have not intentionally quit BitPerfect).  To determine which, open the Activity Monitor.  You will find the Activity Monitor in Finder under "Applications|Utilities".  Alternatively, you can search for it using Spotlight.  The Activity Monitor should contain a list of all currently running process on your Mac. These should be listed in alphabetical order.  If not, just click on the column header labelled "Process Name".  Look to find a process named "BitPerfect".  If it is not there, then BitPerfect has crashed, and you need to follow instructions to locate the Crash Report.  If it is still there it means BitPerfect has hung, and you need to follow instructions to prepare a Process Sample.


Process Sample


In Activity Monitor, click on the listing for BitPerfect, then click on the icon with the gear wheel symbol which drops down a small menu.  Click on 'Sample Process'.  The Process Sample should then appear.  Once it is complete, click on the "Save..." button, and attach the resultant file into an e-mail. Finally, force-quit BitPerfect by clicking on the 'Force a Process to Quit' icon (a grey octagon containing an 'X').


Crash Report


Open the Console App as described above.  In the navigation window, in the section headed by "Diagnostic and Usage Information", in the sub-section "User Diagnostic Reports", look for entries labelled "BitPerfect_YYYY_MM_DD_HHMMSS_xxxxxxx.crash", where "YYYY..." (etc) is a date/time stamp, and "xxxxxx..." describes your Mac.  Right-click on the entry, and select "Mail" to e-mail the result to the BitPerfect Support Line.  There may be multiple crash reports - usually we will want to see them all, but use some common sense to avoid sending crash logs with older date/time stamps that might not be relevant, or that you have already sent to us previously.  However, if in doubt - it is always easiest to just ask!


Device Info Report


Unlike the other reports described above, the Device Info report is generated within BitPerfect.  In BitPerfect's status bar menu, click on "Device Info...".  Copy and paste the resultant report into an e-mail and send it to the BitPerfect Support Line.  It is usually preferable if you generate the Device Info Report while BitPerfect is actually playing music.


The BitPerfect Support Line


To contact BitPerfect Support, send an e-mail to support@bitperfectsound.com.


UPDATE:  If you are using OS X 10.10 (Yosemite) there is a bug in Yosemite which means that BitPerfect sends a stream of messages, several times per second, to the Console Log.  The Console Log has a maximum number of entries it keeps live, and when it fills up, all the older ones are lost.  This bug effectively renders the Console Log useless as a diagnostic tool.

Until Apple comes up with a permanent fix, we have developed a tool you can use to disable these problematic messages.  Using this tool requires a level of comfort with working on OS X at the system level, although hopefully the instructions below are easy enough for most people to use.  As with anything that involves tinkering at the system level, YOU USE THIS TOOL ENTIRELY AT YOUR OWN RISK, AND WITH NO EXPRESS OR IMPLIED WARRANTY.

First, you need to download a special script file which you can download by clicking here.  This will download a file called ConsoleFix.sh.  If you are concerned about the authenticity of this file, the contents are reproduced in this post for you to inspect and compare.

To use the script file, you need to first open a Terminal window.  Inside the terminal window type the following: "sudo bash " - don't type the quote marks, and be sure to leave a space after the bash - and DON'T press the ENTER key.  Next, drag and drop the ConsoleFix.sh file that you just downloaded into the Terminal window.  This action will complete the "sudo bash " line with the full path of the ConsoleFix.sh file.  Now you can press ENTER.  You will be prompted to enter your system password.  Enter it (nothing will show in the Terminal as you type), and hit ENTER.

That's it.  The Console Log should now work fine.  If you want to reset it back to how it was, just re-run the same sequence.  The same command is designed to toggle the modification on and off.