Flash Browser Tracing On Mac, Windows, and Linux

See and hear what your Flash movies (and everyone else's) are doing and saying behind the scenes

Ah, the simple, venerable trace command. Everyone who has ever written even a single line of ActionScript -- from the newbiest of designers to the most seasoned programming professional -- has doubtless become intimately familiar with this most basic, approachable, and useful command. But love turns to hate if you ever need to see what's going on when your Flash movie is playing in a browser, where seeing a simple trace can rapidly become an exercise in frustration. Fret no longer, fearless readers, as this guide aims to get everyone in on that sweet, sweet browser tracing action.

There are a couple of reasons why being able to see ActionScript traces from a browser is important. I already generalized the rationale in the opening paragraph, but it may be worth spelling it out more bluntly: sometimes, once your Flash projects are running in a browser, oddities bubble up. To cite some broad examples which have personally bitten your humble author on the backside, a flashvar may not be what it needs to be, a server-side PHP script could return strange data, or a relative path which worked locally might be just a tad off once on the server. In other words, stuff goes sideways, and if you can't see how things are going wrong in an actual online environment, you're dead in the water.

Another real-world case for tracing Flash output in the browser is user testing. Equipping beta testers with the means to view errors or general output helps enormously when you're shaking down bugs and issues in Flash-based RIAs. Instead receiving user feedback on the order of "I did this, and it didn't work," you can actually get "I did this, and here's the specific error I'm seeing," a scenario which I'd imagine would be more helpful to just about all Flash designers and developers. Unless, of course, you thrive on a certain level of vagueness and uncertainty, in which case I suppose you can stop reading. Otherwise, let's get to how this is set up.

The project

Any Flash project you have lying around that has any trace calls in it would qualify as one to test against, but for the sake of completeness I'm including a very basic project which does nothing more than provide a button that calls a trace statement. You can download the pre-made Flash CS4 project (backsaved to CS3 format in the name of broader compatibility), compiled SWF, and HTML file from this link, or you can create and publish your own version from the following (very basic) steps:

Create a new ActionScript 3 Flash file
Drag a Button out of the Components panel onto the Stage
Name the button instance "btn" using the Properties panel
Create a new layer named "actions" in the Timeline
Select frame 1 in the actions layer
Enter the following code in the Actions panel:

stop();
 
var count:uint = 1;
 
btn.addEventListener(MouseEvent.CLICK, onClick);
 
function onClick(e:MouseEvent):void {
	trace("I am tracing the number " + count);
	count++;
	setLabel(count);
}
 
function setLabel(n:uint):void {
	btn.label = "Trace the number " + n;
}
 
setLabel(1);

Since it's outside the scope of this guide, I'm not going to explain the steps or code in greater detail, but suffice it to say that the project shouldn't be hard to figure out if you're inclined to take a closer look. In any event, if you test the movie (Control: Test Movie) and click on the button while the movie is running, you should see something similar to Figure 1:

Figure 1

And while that's all fine and good, the whole point of this guide is to give you similar feedback while this project is running in a browser, so let's move things along towards that goal.

The Debug Player

If you do any sort of Flash development already, you likely already have the Debug version of the Flash Player. However, it's a safe bet that any end user you may be trying to set up won't, and seeing how browser traces won't show up without it, it's a download worth having. This page always contains the most recent version of the Debug Player, which, as of this writing, is the version of Flash 10 released on July 30, 2009. You'll want to snag the version for whatever platform you're developing on (or that your users are on) and keep it handy. Note that the Windows version has two distinct installers: an ActiveX control for Internet Explorer, and a Netscape-compatible version for everything else. Installation is point-and-click simple on Mac and Windows, as you might expect, though Linux might be another story. I have the latest Ubuntu running in a virtual machine, and with the assistance of this helpful hint, I used apt-get to install the latest non-debug player, downloaded the Debug player for Linux, and then replaced the regular player library with the debug version. If you're comfortable with a command line (even if it's just for simple commands), you'll be fine.

Alternately, if you have Flash CS4 installed on your Windows or Mac system, and are current as far as updates are concerned, the Players folder inside your Flash CS4 program directory should already contain the Windows and Mac versions of the Debug Player, so an extra download may not even be necessary. Once you've run the Debug player installer on your target system, an easy way to determine whether or not it installed correctly is to navigate to any page with an embedded Flash movie, right-click on it, and look at the menu. If it contains entries like "Show Redraw Regions" and "Debugger" (fig. 2), you're good to go.

Figure 2: Ready to rock on (from top) Mac, Windows, and Linux.

One last word of warning for Mac users before moving on: if you have previously installed the Debug Player but have applied a Mac OS X update in the interim (such as the recently released OS X 10.6.2 update), make sure the installed player is still the debug version, as Apple has a habit of overwriting whatever installed Flash Player is present with the most recent non-debug version. You may need to check and re-install if this is the case.

The config file

In order for all those hidden trace statements to become, well, less hidden, you have to arm your machine with a configuration file which, in effect, "tells" the Debug Player to route the traces to a log. Now, you can surf around and get all kinds of information -- some very outdated -- on what specifically to put into this config file, but after a lot of trial and error, there is really only one thing you need to put in it (with an option for a second). But first thing's first: regardless of the platform you are on, fire up whichever plain text editor happens to be convenient/preferred/available. Once it's running, place the following two lines into a new, blank text file:

TraceOutputFileEnable=1 SuppressDebuggerExceptionDialogs=1

Line 1 simply enables the routing of trace outputs to a file, and, as it turns out, is pretty aptly named. It is also the only line needed in the config file in order to enable trace output. In the past, you used to have to set a hard path to the log file, or optionally include things like MaxWarnings to set the number of warnings, but no longer. While TraceOutputFileEnable is mandatory, SuppressDebuggerExceptionDialogs is optional (though I consider it essential). The problem with running the Debug Player by default is that whenever you encounter a SWF that throws a major error, you get something akin to Figure 3:

Figure 3

As you browse the Web, you'll end up seeing this particular annoying dialog ALL THE TIME, as evidently there is a ton of error-filled Flash content out there. These errors all get routed to the trace log anyway, so by including SuppressDebuggerExceptionDialogs=1 in your config file, you won't see that showstopping popup, and can instead use your log viewer (which we'll set up shortly) to see that output only when you're looking for it. So again, it's not strictly necessary, but I consider it vital as a sanity saver.

Now that we know what the config file contents mean, let's save the file. On each platform, this file needs to be saved in the root of the user's home folder as mm.cfg. Both the file name and location have to be exact, or else the traces won't be logged. If you're unsure where the home folder is, here's a quick cheat sheet (substitute your actual user name, of course, for [username]):

Mac OS X: /Users/[username]
Windows XP: C:\Documents and Settings\[username]
Windows Vista and 7: C:\Users\[username]
Linux: /home/[username]

If you've saved your mm.cfg file in the appropriate place, your home folder should look something like one of the shots in Figure 4:

Figure 4: Windows 7 on the left; Mac OS X on the right. Hopefully you get the idea for the other platforms.

The log file

This part often times isn't necessary, but since we need to know where the log file "lives" anyway, we'll power through here. The deal generally is that the first time you visit a page with Flash on it after you install the Debug player AND have added the mm.cfg file, a flashlog.txt file is automatically created for you in the right place. What place is that, might you ask? Time for another quick cheat sheet (again, substitute your real user name in place of [username]):

Mac OS X: /Users/[username]/Library/Preferences/Macromedia/Flash Player/Logs/flashlog.txt
Windows XP: C:\Documents and Settings\[username]\Application Data\Macromedia\Flash Player\Logs\flashlog.txt
Windows Vista and 7: C:\Users\[username]\AppData\Roaming\Macromedia\Flash Player\Logs\flashlog.txt
Linux: /home/[username]/.macromedia/Flash_Player/Logs/flashlog.txt

Keep in mind that only the OS X path remains visible all the way down to the log file. On Windows and Linux, everything after the [username] will probably be hidden by default, meaning you have to show all files and folders in order to visually navigate down to the log file. As for Linux, I'm using Ubuntu, and it's a simple matter of choosing the Show Hidden Files option in the File Browser (fig. 5) and working from there.

Figure 5

On Windows, you have to head to the Folder Options panel (which should be under the Tools menu in XP, Vista, and 7, provided you've chosen to show the menu bar in the latter two) and select the show hidden files and folder option in the View tab (fig. 6).

Figure 6

The reason I'm telling you this now is that occasionally I've seen installs that haven't added the Logs folder or the flashlog.txt file, even though the Debug Player and mm.cfg file have been installed correctly and a SWF file has been viewed in the browser. In the unlikely event that this has happened to you, all you need to do is create the Logs folder and a blank flashlog.txt file at the appropriate OS path shown above. Almost there; let's keep moving.

The viewer

While I suppose you could just open the flashlog.txt file in your favorite text editor and call it a day, that would quickly get annoying, as you would constantly need to reopen the file to see new traces. What would be optimal is to see traces as they happen, without needing to reload anything. Fortunately, that's possible on all of our platforms, though for Windows XP and Vista we need some extra software. And while "hard" is a relative term here, let's work easiest to hardest:

Mac OS X

Mac users, you already have everything you need. The Console application updates as new messages come in, so it's just a matter of opening flashlog.txt and then sitting back with a self-satisfied smirk. To quickly get smirking, launch Console (it's located at /Applications/Utilities/Console.app), select Open from the File menu, and drill down to the flashlog.txt location noted earlier. On subsequent visits to the Console, you should be able to simply pick the flashlog.txt file out of the Open Recent menu.

Linux

Again, I'm basing this on Ubuntu, so adjust as necessary for your particular distro. Fire up the Terminal (Applications:Accessories:Terminal), and enter in the following command at the prompt:

tail -f '/home/[username]/.macromedia/Flash_Player/Logs/flashlog.txt'

Press Enter to run the command, and again, don't forget substitute your real user name for [username]. What you're doing here is issuing the UNIX tail command, which outputs the last part of whatever file you pass to it. The -f flag stands for follow, which will enable the display of new output as it is issued.

Windows 7

We're still in built-in viewer territory with Windows 7's inclusion of PowerShell. Click on the Start Menu, type PowerShell, and then hit Enter. PowerShell will appear, allowing you to enter the following command:

gc "C:\Users\[username]\AppData\Roaming\Macromedia\Flash Player\Logs\flashlog.txt" -wait

Hit Enter, and you're set. Now, I'm no PowerShell expert, but from what I've been able to glean, gc is an alias for the Get-Content command, and tacking on the -wait flag tells it to wait for new output. I could be completely off on that, but since it makes sense, I'm inclined to leave things at "it's working; don't press your luck."

Windows Vista

The procedure for Vista is the same as Windows 7, with the small caveat that you might not have PowerShell installed on your Vista machine. In case the PowerShell entry doesn't show up when you search for it in the Start Menu, you have a couple options. One, look for it as an optional install in Windows Update (which is found in the Control Panel if you're not already familiar), or two, head to this link and follow the instructions to download and install PowerShell. Once you have it, backtrack a bit and follow the same instructions for Windows 7.

Windows XP

This may be the most involved process, but it's not a huge deal in any case. XP has no built-in output viewer suitable for our purposes, but there's a download which fixes that. Head to Microsoft's Windows Server 2003 Resource Kit Tools page and download the rktools.exe package. Ignoring the fact that we're installing something for Windows Server 2003 on XP, it's a double-click to install kind of deal, which I trust you can handle by now. Hidden inside these tools is a Windows-friendly version of the UNIX tail command we went over in the Linux section, which will enable live output through XP's already-resident cmd.exe program. To load up the flashlog.txt file, click on the XP Start Menu and select Run. Type cmd in the Run box, and then hit the OK button. Once XP's command prompt is active, type in the following:

tail -f "C:\Documents and Settings\[username]\Application Data\Macromedia\Flash Player\Logs\flashlog.txt"

Looks familiar, doesn't it? Anyway, hit Enter to execute the command, and everything should be ready. Once more, the usual [username] substitution instruction applies. Now, regardless of your platform, once you have your viewer up and running and following the output of the flashlog.txt file, we're ready for our last step.

Trying it out

Ready for the big finish (such as it is)? OK, here we go. Whether you've downloaded the pre-built project from earlier or rolled your own from the instructions above, it's time to open the HTML page linking to our simple trace button. Once you've done that, arrange your browser and viewer windows so that you can see both, and click away. If all has gone according to our diabolical plan, you should see results. Check out Figure 7 to see what you should be seeing:

Figure 7: (from top) Mac, Windows XP, Windows Vista, Windows 7, and Ubuntu all tracing their little behinds off.

Well, there you have it: Flash tracing from the browser, on every platform which supports the official Flash Player. Now, it's worth noting that it may be fun (and perhaps educational) to watch the output log as you view any Flash page, as all traces from any Flash movie will be routed to your log. There's a lot of interesting stuff to see behind the scenes, not only for your own projects, but from everyone else's as well. Enjoy, and, as always, be sure to use your newfound powers for good and not evil.

Filed under: Tutorial on December 1st, 2009
Tags: Flash, Flash Player

^ Top of Page

Got Feedback? to send an email. I'll do my best to answer. Really.

…by Kevin Schmitt