The Instrumentation Log window is almost always the best method for monitoring instrumentation as you debug. It’s built into Panorama and very simple to use. However, you can also monitor the instrumentation with an external program – either Terminal.app or BBEdit.app.

Note: The techniques described on this page are different than the techniques shown in the Crash Proof Debug Instrumentation Monitoring page. The techniques described on this page work by writing the instrumentation log to a text file, then using an external program to display the text file. If Panorama crashes, it may not get a chance to completely write the log to the text file – the end of the log may be missing. The “crash proof” method doesn’t use a text file (though you can still separately enable writing to the text file) – it sends the log entries directly to the external program (either Console.app or Terminal.app). This happens instantaneously and won’t be interrupted by a crash, so the log display is always correct up to the instant of the crash. The downside is that special setup is required to use the crash proof method. The methods described on this page do not require any special setup.

Dynamic Monitoring via Terminal.app

Terminal.app is a utility program that Apple includes on all macOS computers (so you already have it installed). To start monitoring Panorama instrumentation using Terminal.app, click on the Instrumentation menu and choose Monitor Log in Terminal.app.

If the Instrumentation Preference panel is open, you can also start the monitor from the pop-up menu attached to the gear icon.

Either way, Terminal.app will open with a new window. This new window will show recent Panorama instrumentation activity, and will automatically update as new activity occurs.

Dynamic monitoring will continue for as long as you leave the Terminal.app window open. You can even quit Panorama and re-open it, and monitoring will continue. When you want to stop dynamic monitoring, close the Terminal.app window:

When asked if you want to terminate running processes, press the Terminate button. (Technical note: This will terminate the tail shell command. The tail command is what is actually providing the dynamic monitor.)

If you want to stop dynamic monitoring without closing the Terminal.app window, click on the window and then press Control-C.

This allows you to continue viewing the instrumentation information, but new information won’t appear.

If you hold down the Option key when choosing the Monitor Log in Terminal.app menu item, Panorama will archive the existing instrumentation log, then start a fresh new log. (Of course you can also manually choose Clear Log or Archive Log.)

Dynamic Monitoring via BBEdit

Another alternate way to dynamically monitor the instrumentation log is using the BBEdit text editor from Bare Bones Software. BBEdit is a popular text editor program written by Bare Bones software. A possible advantage of using BBEdit is that it is a full text editor, so unlike Panorama’s built in Instrumentation Log window you can search and edit the log as you monitor it.

If you don’t already have a copy BBEdit, a free version is available on the Mac App Store or directly from the Bare Bones web site (https://www.barebones.com). The free version doesn’t have all of the fancy bells and whistles of the paid version, but it will work for dynamic monitoring of Panorama instrumentation logs. Important: The dynamic monitoring feature only works with BBEdit 14.5 or later.

To start monitoring Panorama instrumentation using BBEdit, click on the Instrumentation menu and choose Monitor Log in BBEdit. (If the Instrumentation Preference panel is open, you can also start the monitor from the pop-up menu attached to the gear icon.)

When you choose this command, BBEdit will open with a new window. (If this doesn’t work, make sure you have BBEdit 14.5 or newer installed on your computer.) This new window will show recent Panorama instrumentation activity, and will automatically update as new activity occurs.

As you can see, this window looks very similar to the same display in the previous section using Terminal.app. So why would you go to the trouble of installing and using BBEdit instead of using Terminal.app? The advantage of BBEdit is that it is a full featured text editor, with powerful searching and other useful features. If your instrumentation logs get large (and they can quickly grow to hundreds of thousand of characters if you are debugging a complex program), BBEdit also has much better performance than Terminal.app for such large amounts of text. It only takes a couple of minutes to install BBEdit, and we think it is well worth it if you plan to use debug instrumentation on a regular basis.

The Instrumentation menu also has an Open Log in BBEdit command. This allows you to view the log, but does not enable dynamic monitoring. Usually there is no reason to use this command, since it won’t show new activity as it happens.

See Also

• Client/Server Debug Instrumentation -- using instrumentation with Panorama X server and clients.
• Coding with Debug Instrumentation -- modifying your code to generate debug instrumentation output.
• Crash Proof Debug Instrumentation Monitoring -- real time crash-proof instrumentation monitoring
• Customizing Debug Instrumentation Coverage -- specifying what code is being debugged at the moment.
• Debug Instrumentation -- conditional logging of the internal state of Panorama program code.
• Debug Instrumentation Log Window -- dynamically monitor debug instrumentation output as your program runs.
• Debug Instrumentation Text File -- configuring and accessing the debug instrumentation log (text) file.
• info("runningunderterminal") -- returns the name of the terminal program if Panorama was launched under one, otherwise it returns empty text.
• labelize( -- returns the value of a field or variable along with a label. This saves typing when you need to display fields or variables when logging and debugging.
• labelizeformula( -- returns the value of a formula along with the formula itself as a label.
• labelizeinfo( -- returns the value of an info( function, along with the function itself as a label.
• labelizepattern( -- formats a text value using a label and a pattern.
• Recording Code Triggers in Debug Instrumentation -- the code triggers option automatically tracks whenever any code is triggered, whether from a menu, a button, or implicitly (for example when data is entered).
• Recording Control Flow in Debug Instrumentation -- configure debug instrumentation to automatically log when control flow is non-linear, for example a call, return, goto, etc.
• setzlog -- turns instrumentation coverage on or off for a specific procedure (or all procedures within a database).
• zlog -- outputs a message to the instrumentation log (if instrumentation is enabled).
• zlogalways -- unconditionally outputs a message to the instrumentation log.
• zlogcoverage -- allows instrumentation coverage to be turned on or off within a procedure.
• zlogdictionary -- outputs a data dictionary to the instrumentation log (if instrumentation is enabled).
• zlogging( -- returns true if zlogging is enabled for the current database and procedure, otherwise false.

History