A Console replacement for examining past logs: LogLogger5

Examining the logs in OS X / macOS is a very important function when investigating many problems. The logs can reveal what happened when, and give you powerful clues as to why things went wrong, enabling you to fix those problems. Even simple tasks, like checking whether the last Time Machine backup completed without errors, become impossible without access to the logs.

With macOS Sierra, Apple has introduced a completely new and very powerful log system, with much greater capabilities than that in El Capitan (or, indeed, other comparable operating systems). However its current app for accessing those logs, Console 1.0, has almost no features to access the logs from the past, even a second before you start the app. In macOS Sierra 10.12 and 10.12.1, the only way of gaining useful access to logs of the past is through the command tool log (which is not without its own problems).

LogLogger5 is my new and much-improved version of a simple AppleScript app to give as complete access to past logs as you might obtain using the log show command in Terminal. Among its improvements are:

  • it no longer displays an irritating startup alert before getting on with the job,
  • it now runs in an infinite loop (until you cancel it) to help you hone in on the log entries which you need,
  • it makes entry of start and end times much easier,
  • it can automatically open the log excerpts which it creates using your default text editor, whilst it is running, so that you can browse excerpts before obtaining another,
  • it can name excerpt files serially, for speed of use,
  • it retains many of its settings while running to save you having to re-enter them, but these are currently lost when you quit it.

If you want to distribute it more widely, please link to this page, with its detailed instructions and explanations. I don’t wish to prevent anyone from making copies available elsewhere, but it does not come with instructions. Here is the zipped app for download: loglogger5

It is an unsigned app, which uses Shane Stanley’s neat Dialog Toolkit v2.0.2 (which is included in the bundle, so that you don’t have to install that separately). It is unsigned so that you can improve on it, and customise it as you wish – if I had signed it, that should break the signature. But it does mean that when you first run it after downloading, you will have to do so using the Finder’s Open command, or Gatekeeper will prevent it from running.

loglogger51

When you run LogLogger5, you will first be prompted for the name of the text file into which the log excerpt will be written. This is a standard file save dialog, so clicking on the expand tool will transform it into the full dialog, as usual. I recommend that you keep to the basic format of file name given: the two digits will be automatically incremented each time that you save a new log excerpt, sparing you from having to do that manually. The .text file extension ensures that your Mac knows the document is plain text.

To quit LogLogger5 from here, just click on the Cancel button. If you click on the Save button, the file will be created in the normal way, and you will then be presented with the app’s main dialog.

loglogger52

It is then driven from this dialog.

The first section sets any predicates to be used to filter the entries to be included in its output. If you just want Time Machine entries, leave the button set to that. If you want all log entries (beware: for any length of time the output file will be huge), set it to none.

The other two radio buttons require you to enter predicate information below.

Pattern lets you create one or two filter terms using the popup menus and text boxes below. If you select this, you must configure at least the first Pattern line.

The two lines which start with Pattern: let you build the most popular filter expressions. If you set both, then the Logical operator (by default AND) will be applied to combine them.

The first popup menu in each of the two Pattern lines determines what is examined in the filter. On offer are:

  • eventMessage – for this, you specify a text pattern, or text, within the message, or an activity name.
  • processImagePath – this matches the text pattern in the name of the process which originated the event.
  • senderImagePath – this matches the text pattern in the name of the sender, which might be the name of a library, extension, or executable.
  • subsystem – this matches the subsystem specifier, e.g. com.apple.TimeMachine. Although potentially valuable, subsystems are not yet widely used, and discovering which is which is not easy. Use with caution.

The Operator popup menu in each of the two Pattern lines determines what the filter actually does. Operators available include:

  • == is the equality operator, as in == “com.apple.TimeMachine”
  • != is the inequality operator
  • BEGINSWITH is for text which begins with the quoted text, and is case- and diacritic-sensitive
  • CONTAINS is for text which contains the quoted text, and is case- and diacritic-sensitive
  • CONTAINS[c] is for text which contains the quoted text, and is case-insensitive and diacritic-sensitive
  • ENDSWITH is for text which ends with the quoted text, and is case- and diacritic-sensitive

Logical operators which can be used to combine two filter patterns include:

  • AND which is simple, logical AND – both patterns are true
  • OR is simple, logical OR – either pattern is true
  • AND NOT is logical and, but the second pattern is NOT true
  • OR NOT is logical or, but the second pattern is NOT true.

For example, shortly after restarting from a freeze I ran the app to show all the kernel entries from just before the freeze until the current moment. To do that, I set up just the first Pattern line, to read
processImagePath CONTAINS[c] kernel

Note that when you use the log command in Terminal, you must insert text in quotation marks ” “. In the final text boxes for Patterns, do not use quotation marks unless they are part of the search string: LogLogger5 automatically puts the contents of the Text boxes into quotation marks when it builds the command.

other allows you to enter any other valid predicate which you wish, such as that shown by default in the Other box below: here you need to give the full predicate, including any ” ” for text, which will simply be placed inside single quotes ‘ ‘ and prefaced by --predicate

The middle section concerns the style and formatting of the output. The standard is to use traditional system log style, similar to the previous Console app. You will probably want that with the trim feature turned on, to make the lines more compact. The default style is based on the new logs’ content, which is much more extensive and detailed. You will want to turn trimming off in that case. The final option for JSON format is valuable if you want to read the log output into another app which takes JSON format; don’t use trim with that, or it will become a real mess.

Normally you should include info messages: this does make a difference.

The third section concerns the period of logs to cover. There are two ways to specify this: a period of time up to the present, or start and end times, and the app now provides for both. If you enter a non-zero positive integer into the Period text box, then the log excerpt will cover that period up to the present moment. If you leave the period set to zero (0), then the start and end times will be used instead.

With a positive integer entered into the Period box, you need to set the Unit of time, which defaults to seconds for safety. Units are selected from seconds, minutes, hours, or days.

Start and end dates are initially set to today’s date and the time that you start the app. Ensure that both their checkboxes are checked (or they will be omitted, and possibly result in a vast log excerpt), and edit the dates and times in the standard format. Using other formats will almost certainly result in errors, and unexpected results.

The final section allows you to open the resulting file in your default text editor (usually TextEdit), and add any other text you want to the log show command. If you leave that text box blank (the default), then no additional text will be added to the command, which is the normal way to run LogLogger5.

If you click on the OK button, after a few seconds or longer, the requested log excerpt should then be saved into your specified text output file, and opened in your text editor if you opted for that to happen. If you click on the Cancel button, LogLogger5 will quit.

If you use the standard syslog style with trimming, the first line will normally be junk, thereafter it will look something like
2016-10-12 18:19:34.49 backupd[10374]: (TimeMachine) [com.apple.TimeMachine.TMLogInfo] Starting automatic backup
2016-10-12 18:19:34.77 backupd[10374]: (TimeMachine) [com.apple.TimeMachine.TMLogInfo] Backing up to /dev/disk3s2: /Volumes/PROMISE PEGASUS/Backups.backupdb
2016-10-12 18:19:35.60 UserEventAgent[66]: (TimeMachine) [com.apple.TimeMachine.TMLogError] Failed to send message because the port couldn't be created.
2016-10-12 18:19:37.66 backupd[10374]: (TimeMachine) [com.apple.TimeMachine.TMLogInfo] Will copy (75.4 MB) from Macintosh HD
2016-10-12 18:19:37.67 backupd[10374]: (TimeMachine) [com.apple.TimeMachine.TMLogInfo] Found 573 files (75.4 MB) needing backup

and so on.

Having clicked on the OK button and obtained your log excerpt, the app then returns to present you with the file save dialog again, to create another log extract. This loop will continue until you either cancel on the file save dialog, or cancel on the main app dialog.

Examples

If you simply want to check that the last 4 hours of Time Machine backups were made without error, all you have to do is start the app, ensure the log excerpt is saved in the right place using its default name, enter the digit 4 into the Period box mid-way down the dialog, and set the Unit of time to h for hours. If you want the log excerpt opened automatically, ensure that the bottom checkbox to open in editor is checked, then click on OK. When the file save dialog appears a second time, just cancel it, and you’re done. It is that quick and simple.

loglogger53

If you want to inspect the logs for a period prior to a forced restart, select the Pattern radio button at the top of the dialog, the first popup menu to eventMessage, the Operator to CONTAINS(c), and enter the Text BOOT_TIME. Leave the Period set to zero, and set the start time to a few minutes before the restart occurred. Check the box to open the excerpt in your text editor, and click on OK.

In a few seconds, the log excerpt will open, showing the exact time of the startup. In your Dock, click on the LogLogger5 app (which will be bouncing enthusiastically), and click on OK to save the next excerpt. When the dialog appears, select the Pattern radio button again, and set the first pattern up to processImagePath, with the Operator CONTAINS(c), and the text kernel.

loglogger54

Move down the dialog and set the end time to that shown in the last log excerpt for the startup, and the start time to a couple of minutes beforehand. Click on the OK button, and the excerpt saved and opened for you will contain all the log messages from the kernel for the two minutes before that forced restart – a good step towards working out what was going on.

You can find other tips on useful predicates in this article.

I hope that you find this a practical tool which helps you diagnose issues. If you have any problems, find bugs, or have any suggestions, please add them here as comments (or send them by email to me).