MACRO: Engine.log Tool, v8.0

Main Dialog

With the exception of Done, all main dialog buttons can be selected by typing the first letter of the button label. Done can be selected by pressing <esc>.

Help Displayed

The help window describes the primary function and additional functions (invoked by combining Command (⌘), Option (⌥), or Control (⌃)) of each button.


Expanded Dialog

Display of variables can be toggled by holding down the Control key (⌃) when the Previous, Next, or Latest button is clicked.


Reduce Button Displays Secondary Functions

These secondary functions can be used to delete all or some of the entries in the Engine.log.


Select a Failure or Timeout

A list of Failures and Timeouts can be displayed by holding down the Command key (⌘) when the Last button is clicked. A selected item will then be displayed in the main dialog.


Additional Options

A list of additional options can be displayed by holding down the Command key (⌘) when the Done button is clicked.


PURPOSE

The primary function of the macro is to use a dialog box to display the latest Keyboard Maestro failure or timeout by searching through the Keyboard Maestro Engine.log. After the latest failure/timeout is displayed, the macro provides an option to back through earlier failures/timeouts.

The dialog box also provides an option to display the log file in the Console application with the error line selected and another option to display the offending action in the Keyboard Maestro editor. Other, less frequently used, dialog options are summaried in the macro Help window.

The macro also the option to display a small window that displays the the name of the macro that contains the action that failed or timed out.

If the hot key trigger includes the Shift key (⇧), or the %TriggerValue% includes recall (see below), the initially displayed failure|timeout will be the one last viewed when the macro previously ran.

A secondary function of this macro is to delete some (or all) entries in the Engine.log via seven reduction methods:
delete ⇨ delete Engine.log
purge:RegEx ⇨ modify Engine.log, retaining all entries except those that match the RegEx
keep:RegEx ⇨ modify Engine.log, retaining all entries that match the RegEx
tail:n ⇨ modify Engine.log, retaining only the latest n entries
today ⇨ modify Engine.log, retaining only entries since midnight
days:n ⇨ modify Engine.log, retaining only the latest n days of entries (e.g., days:2 == since midnight yesterday)
time:YYYY-MM-DD [hh:mm[:ss]] ⇨ modify Engine.log, retaining only records since the specified date/time

Note: In all cases, a copy of the unmodified Engine.log is send the System Trash before the log is deleted or reduced.

These reduction methods become available if the dialog box Reduce button is selected.

EXECUTING THIS MACRO FROM ANOTHER MACRO AND/OR BY USING APPLESCRIPT

If this macro is run from another macro using the Execute a Macro action (or via AppleScript), and With Parameter is specified, the following keywords will direct the macro to execute accordingly.

null : run in normal mode.
recall : the initially displayed failure|timeout will be the one last viewed when the macro previously ran

console : bypass the macro dialog box, i.e., go directly to the Console.app with the failed|timed out action selected

action : bypass the macro dialog box, i.e., go directly to the failed|timed out action in the Keyboard Maestro editor
reduce : bypass the macro dialog box and go to the Reduce Prompt With List

clipboard : bypass the macro dialog box and save the latest failure or timeout to the clipboard
editor : bypass the macro dialog box and open the Engine.log in a text editor
reveal : bypass the macro dialog box and reveal the Engine.log in the Finder
select : bypass the macro dialog box and go to the Failure|Timeout Prompt With List
tail : bypass the macro dialog box and run the Terminal command tail -F Engine.log

delete ⇨ delete Engine.log
purge:RegEx ⇨ modify Engine.log, retaining all entries except those that match the RegEx
keep:RegEx ⇨ modify Engine.log, retaining all entries that match the RegEx
tail:n ⇨ modify Engine.log, retaining only the latest n entries
today ⇨ modify Engine.log, retaining only entries since midnight
days:n ⇨ modify Engine.log, retaining only the latest n days of entries (e.g., days:2 == since midnight yesterday)
time:YYYY-MM-DD [hh:mm[:ss]] ⇨ modify Engine.log, retaining only records since the specified date/time

Note: When the above reduction methods (indicated with a ⇨) complete, a dialog box appears summarizing the status of Engine.log. This dialog box can be suppressed by adding a 0: prefix (i.e., 0:delete).

SETTINGS

local_DialogVariables : 0|1; default 0 : when the main dialog is displayed, the Time, Action, and Description variables will be included. Note that this value can be toggled by holding the Control key (⌃) when the < Previous, Next >, or Latest button is clicked.

local_BoundaryAlert : 0|1|2|3; default 1 : when attempting to go after that the latest Failure|Timeout or before the earliest using the Next > or < Previous, respectively, a audible and/or visual alert can occur.

0 : no alert
1 : Basso sound
2 : Display Text Large banner
3 : both sound and banner

local_ShowMacroWindow: 0|1; default:1 : A small window will appear that displays the the name of the macro that contains the action that failed or timed out.

local_DescendingIsDefault : 0|1; default:1 : when the Engine.log entries appear in a Prompt For User Input (⌘+Latest button) or are opened in the text editor (⌘+Console button), the latest entry will be at the top. If the Option key (⌥) is also down when the Latest or Console button is clicked, the order will be reversed.

The two settings below can be found within the Group named Process the extracted Engine Log Failure|Timeout line, the Switch/Case action, Console option. (Actions are colored orange to help find these settings.) These settings apply when the Command key (⌘) is down when the Console button is clicked.

  1. local_TextEditorLogEntriesCnt : n; default:500 : maximum number of Engine.log entries that will be opened in the configured text editor

  2. The preferred text editor (default:Default Application) can be set within the Open a File Folder or Application action.

TESTED WITH

• Keyboard Maestro 11.0.2
• Sonoma 14.2 (23C64)/MacBookPro18,2
• Sonoma 14.2 (23C64)/VariableMacBookPro16,1
• Mojave 10.14.16/Macmini6,2
• High Sierra 10.13.6/iMac11,1445

VERSION HISTORY

( expand / collapse )

1.0 - initial version

1.1
a) Improved performance for large Engine.log files.

b) Added Adjustable Variables that can be optionally modified to tune the macro performance.

2.0
a) Changed the macro name from Action Failures & Timeouts in Engine Log to Engine.log Tool.

b) Modified the main dialog box to include the Engine.log entry count and to better highlight the failure|timeout.

c) Renamed the button Log to Console.

d) Modified the logic to minimize the pause required before the Console option Edit > Find > Find... is completed. This change eliminated the need for two of the three Adjustable Variables added in Version 1.1.

e) If the hot key trigger includes the Shift key (⇧) or the %TriggerValue% includes recall, the initially displayed failure|timeout will be the one last viewed when the macro previously ran.

f) Improved performance (slightly) and added a check if Engine.log does not contain any failures|timeouts.

g) If this macro is run from another macro using the Execute a Macro action (or via AppleScript), and With Parameter is specified, the following keywords will direct the macro to execute accordingly:
recall : the initially displayed failure|timeout will be the one last viewed when the macro previously ran

console : bypass the macro dialog box, i.e., go directly to the Console.app with the failed|timed out action selected
action : bypass the macro dialog box, i.e., go directly to the failed|timed out action in the Keyboard Maestro editor

delete : delete Engine.log
purge:RegEx : modify Engine.log, retaining all entries except those that match the RegEx
keep:RegEx : modify Engine.log, retaining all entries that match the RegEx
tail:n : modify Engine.log, retaining only the latest n entries
today : modify Engine.log, retaining only entries since midnight
days:n : modify Engine.log, retaining only the latest n days of entries (e.g., days:2 == since midnight yesterday)
date:YYYY-MM-DD [hh:mm[:ss]] : modify Engine.log, retaining only records since the specified date/time

When the above reduction methods complete, a dialog box appears summarizing the status of Engine.log. This dialog box can be suppressed by adding a 0: prefix (i.e., 0:delete).

2.1 Bug fix: Progress dialogs were being displayed even if Engine.log Tool was being run silently from another calling macro.

3.0 Streamlined the main dialog, added a Help button, and moved the instructional information to a help window.

4.0
a) If the Command key (⌘) is down when the Console button is selected, a truncated version of the Engine.log will be opened in a configured text editor. Three settings (and default) have been added: local_TextEditorLogEntriesCnt (500), local_DescendingEntries (1), and the text editor (TextEdit) in an Open a File Folder or Application action.

b) If the Command key (⌘) is down when the Done button is selected, a Prompt With List appears with six options:

  • Reveal the Engine.log in the Finder
  • Save the Last Displayed Failure|Timeout to the Clipboard
  • Save the n Displayed Failure|Timeout to the Clipboard
  • Save the n Displayed Failure|Timeout to the Clipboard (descending)
  • Run 'Engine.log Tool' in Test Mode
  • Quit

c) Updated the Help to include the Command key (⌘) options. The Help window is now overlapped slightly to save vertical footprint.

d) Added a setting: local_BoundaryAlert : 0|1|2|3; default 1 : when attempting to go after that the latest Failure|Timeout or before the earliest using the Next > or < Previous, respectively, a audible and/or visual alert can occur.

5.0
a) Modified the behavior when the Command key (⌘) is down when the Console button is selected (a feature added in Version 4.0):

  1. The output file directory was changed from ~/Desktop to /tmp,

  2. setting local_DescendingEntries was dropped and setting local_DescendingIsDefault was added, and

  3. the Open a File Folder or Application action was changed from TextEdit to Default Application. The Open a File Folder or Application action can be changed to a specific text editor if one wants to override the Default Application.

b) If the Command key (⌘) is down when the Reduce button is selected, the delete Engine.log option will be initiated.

c) If the Command key (⌘) is down when the Latest button is selected, a Prompt With List will appear that includes the most recent Failures|Timeouts (up to a maximum of 95). When a selection is made, the main dialog opens with that item displayed.

d) If the Command key (⌘) is down when the Done button is selected, the Prompt With List items have been rearranged:

  • Save the Last Displayed Failure|Timeout to the Clipboard
  • Save the n Displayed Failure|Timeout to the Clipboard
  • Save the n Displayed Failure|Timeout to the Clipboard (descending)
  • Reveal the Engine.log in the Finder
  • Run 'Engine.log Tool' in Test Mode
  • Cancel Macro

e) If the Engine.log doesn’t contain any Failures|Timeout, the process to add one of each has been simplified. Also, the Timeout is now added without generating a notification.

f) Changed local_LogTailCount default value from 1000 to 5000.

g) Added a Cancel Macro option to each of the Prompt With List actions.

h) Updated the Help to include the new Command key (⌘) options.

6.0
a) If the Command key (⌘) is down when the Done button is selected, added an option to invoke the Terminal command tail -F Engine.log.

b) If this macro is run from another macro using the Execute a Macro action (or via AppleScript), and With Parameter is specified, the following keywords have been added:

clipboard : bypass the macro dialog box and save the latest failure or timeout to the clipboard
editor : bypass the macro dialog box and open the Engine.log in a text editor
reduce : bypass the macro dialog box and go to the Reduce Prompt With List
reveal : bypass the macro dialog box and reveal the Engine.log in the Finder
select : bypass the macro dialog box and go to the Failure|Timeout Prompt With List
tail : bypass the macro dialog box and run the Terminal command tail -F Engine.log

c) Updated the Help window.

7.0
a) Added a new setting local_DialogVariables : 0|1; default 0 : when the main dialog is displayed, the Time, Action, and Description variables will be included. Note that this value can be toggled by holding the Control key (⌃) when the < Previous, Next >, or Latest button is clicked.

b) Bug fix: If the macro trigger includes the Shift key (⇧), the macro correctly recalls the previously displayed Failure|Timeout. (That feature was broken in Version 6.0.)

8.0

a) The main dialog has been changed such that all buttons, with the exception of Done, can be selected by typing the first letter of the button label. Done can be selected by pressing <esc>.

b) When the Console or Action buttons are selected, the main dialog no longer closes. Note that it can easily be dismissed with the <esc> key. The Engine.log can be forced to reload, by holding down Control (⌃) when the Console button is clicked. (This could be useful when monitoring a macro under development, however, a more efficient method would likely be the use of tail -F Engine.log available by holding down Command key (⌘) when clicking Done.)

c) With help from @ComplexPoint, added an optional small window that displays the the name of the macro that contains the action that failed or timed out. (There will be a noticeable delay before this small window appears. For more information, see this thread.) By default, this small window will appear for every viewed failure/timeout, but that can be changed with a new SETTING named local_ShowMacroWindow. As the macro is running, this state can be toggled by holding down Option key (⌥) when clicking the Action button. In addition, this small window can be opened on demand for the currently viewed failure/timeout, by holding down the Command key (⌘) when clicking the Action button.

d) Added seven additional options with modifiers: 1-3) the three modifiers mentioned above; 4) retreat or advance by 5 failures/timeouts; 5) retreat or advance by 10 failures/timeouts; 6) delete all log items except the latest n where n = 100 by default; 7) save the latest displayed Failure/Timeout to the Clipboard.

e) Modified the AppleScript used to close the Help window. The revised version is easier to understand; it might help address an issue reported by @Nr.5-need_input.

f) If running macOS Mojave or older, the main dialog vertical dividing lines are slightly shorter.

g) Updated the Help window: 1) added the seven new options, 2) changed the primary font color to a darker grey, changed buttons to red, changed modifiers to a darker grey, and 3) increased the vertical space between bullets.


Upgrading from an Earlier Versions of Engine.log Tool

If an earlier version is installed, the upgrade will be easier if the previous version of Engine.log Tool and any calling macros are first deleted. The download file below will install a total of 17 macros, however, the 16 calling macros are very short and simple.


If upgrading from an earlier version of Engine.log Tool, please follow the instructions above.

Download: Engine.log Tool Macros.kmmacros (606.6 KB)

Macro-Image


Macro-Notes
  • Macros are always disabled when imported into the Keyboard Maestro Editor.
    • The user must ensure the macro is enabled.
    • The user must also ensure the macro's parent macro-group is enabled.

System Information
  • macOS 14.4.1 (23E224)
  • Keyboard Maestro v11.0.2

Help button: Opens a window that describes the function of each dialog button.

01 Help


Console button: Opens the Console application and automatically finds (thus highlights) the failure or timeout that was displayed in the main dialog.

02 Console


Action button: Opens the Keyboard Maestro application and automatically selects the failure or timeout that was displayed in the main dialog.

03 Action


Reduce button: Displays the menu of seven methods to reduce the size of the Engine.log.

04 Reduce


tail:n (reduce method) ⇨ modify Engine.log, retaining only the latest n entries

05 Tail


purge:RegEx (reduce method) ⇨ modify Engine.log, retaining all entries except those that match the RegEx

06 Purge


The Engine.log reduction methods can be triggered from a calling macro. One possible application is to remove entries from frequently run macros that clutter the Engine.log. For example, if macros ABC and XYZ are such macros, these steps could be employed:

  1. Download and install Engine.log Tool Macros (link above).

  2. Duplicate the macro: Engine.log Tool–21 purge:RegEx

Keyboard Maestro Export

  1. Rename the duplicated macro: Engine.log Tool–purge:ABC and XYZ entries silently

  2. Modify the With Parameter in the duplicated macro to purge the entries for ABC and XYZ. (Optionally Engine.log Tool is included to purge Engine.log of this macro as well.) The 0: prefix instructs Engine.log Tool to run silently.

Keyboard Maestro Export

  1. For Engine.log Tool–purge:ABC and XYZ entries silently set a Periodic Trigger.
11 Likes

I’ve been looking to replace the macro I use to show the last few errors and I think this might be the one, Jim! I’ll definitely give this some testing tomorrow. :sunglasses:

1 Like

Very cool, thank you!

My machine (on Monterey) hiccuped trying to paste into the Find field in Console until I added a pause between the Reload and Find Select actions here:

.2 and .3 still hiccuped, but .6 did the trick.

Thanks again :+1:

1 Like

Hi, @evanfuchs; you’re welcome!

Ha, I had the reload in there only for testing and forgot to remove it. If you have time, please disable it and your pause and let me know how that works for you. Thanks!

On first read, I thought that made sense, but it seems I still need the Pause after opening Console, anywhere between the Open and Select "Find..." actions. Even with reload disabled.

1 Like

Thanks for reporting back. I’ll take another look this evening when I return home.

Nice Macro @_jims!

Thank you for sharing.

KC

1 Like

I've updated the OP with Version 1.1 of Action Failures & Timeouts in Engine Log:

  • Improved performance for large Engine.log files.

  • Added Adjustable Variables that can be optionally adjusted to tune the macro performance.

I've updated the OP with Version 2.0 of Engine.log Tool:

  • Changed the macro name from Action Failures & Timeouts in Engine Log to Engine.log Tool.

  • Modified the main dialog box to include the Engine.log entry count and to better highlight the failure|timeout.

  • Renamed the button Log to Console.

  • Modified the logic to minimize the pause required before the Console option Edit > Find > Find... is completed. This change eliminated the need for two of the three Adjustable Variables added in Version 1.1.

  • If the hot key trigger includes the Shift key (⇧) or the %TriggerValue% includes recall, the initially displayed failure|timeout will be the one last viewed when the macro previously ran.

  • Improved performance (slightly) and added a check if Engine.log does not contain any failures|timeouts.

  • If this macro is run from another macro using the Execute a Macro action (or via AppleScript), and With Parameter is specified, the following keywords will direct the macro to execute accordingly:
    recall : the initially displayed failure|timeout will be the one last viewed when the macro previously ran

    console : bypass the macro dialog box, i.e., go directly to the Console.app with the failed|timed out action selected
    action : bypass the macro dialog box, i.e., go directly to the failed|timed out action in the Keyboard Maestro editor

    delete : delete Engine.log
    purge:RegEx : modify Engine.log, retaining all entries except those that match the RegEx
    keep:RegEx : modify Engine.log, retaining all entries that match the RegEx
    tail:n : modify Engine.log, retaining only the latest n entries
    today : modify Engine.log, retaining only entries since midnight
    days:n : modify Engine.log, retaining only the latest n days of entries (e.g., days:2 == since midnight yesterday)
    date:YYYY-MM-DD [hh:mm[:ss]] : modify Engine.log, retaining only records since the specified date/time

    When the above reduction methods complete, a dialog box appears summarizing the status of Engine.log. This dialog box can be suppressed by adding a 0: prefix (i.e., 0:delete).

2 Likes

Thanks for the update Jim!

The previous version is my goto tool for tracking down errors so I’m really looking forward to using version 2 with its enhancements.

Snappier name too :wink:

1 Like

I've updated the OP with Version 2.1 of Engine.log Tool:

  • Bug fix: Progress bars were being displayed even if Engine.log Tool was being run silently from another calling macro.

WOW I'm in love, thank you!

1 Like

I've updated the OP with Version 3.0 of Engine.log Tool:

  • Streamlined the main dialog, added a Help button, and moved the instructional information to a help window.
1 Like

I've updated the OP with Version 4.0 of Engine.log Tool:

  • If the Command key (⌘) is down when the Console button is selected, a truncated version of the Engine.log will be opened in a configured text editor. Three settings (and default) have been added: local_TextEditorLogEntriesCnt (500), local_DescendingEntries (1), and the text editor (TextEdit) in an Open a File Folder or Application action.

  • If the Command key (⌘) is down when the Done button is selected, a Prompt With List appears with four options:

    • Reveal the Engine.log in the Finder
    • Save Last Displayed Failure|Timeout to the Clipboard
    • Save All Displayed Failure|Timeout to the Clipboard
    • Save All Displayed Failure|Timeout to the Clipboard (descending)
    • Run 'Engine.log Tool' in Test Mode
    • Quit
  • Updated the Help to include the Command key (⌘) options. The Help window is now overlapped slightly to save vertical footprint.

  • Added a setting: local_BoundaryAlert : 0|1|2|3; default 1 : when attempting to go after that the latest Failure|Timeout or before the earliest using the Next > or < Previous, respectively, a audible and/or visual alert can occur.

2 Likes

I've updated the OP with Version 5.0 of Engine.log Tool:

  • Modified the behavior when the Command key (⌘) is down when the Console button is selected (a feature added in Version 4.0):

    1. The output file directory was changed from ~/Desktop to /tmp,

    2. setting local_DescendingEntries was dropped and setting local_DescendingIsDefault was added, and

    3. the Open a File Folder or Application action was changed from TextEdit to Default Application. The Open a File Folder or Application action can be changed to a specific text editor if one wants to override the Default Application.

  • If the Command key (⌘) is down when the Reduce button is selected, the delete Engine.log option will be initiated.

  • If the Command key (⌘) is down when the Latest button is selected, a Prompt With List will appear that includes the most recent Failures|Timeouts (up to a maximum of 95). When a selection is made, the main dialog opens with that item displayed.

  • If the Command key (⌘) is down when the Done button is selected, the Prompt With List items have been rearranged:

    • Save the Last Displayed Failure|Timeout to the Clipboard
    • Save the n Displayed Failure|Timeout to the Clipboard
    • Save the n Displayed Failure|Timeout to the Clipboard (descending)
    • Reveal the Engine.log in the Finder
    • Run 'Engine.log Tool' in Test Mode
    • Cancel Macro
  • If the Engine.log doesn’t contain any Failures|Timeout, the process to add one of each has been simplified. Also, the Timeout is now added without generating a notification.

  • Changed local_LogTailCount default value from 1000 to 5000.

  • Added a Cancel Macro option to each of the Prompt With List actions.

  • Updated the Help to include the new Command key (⌘) options.

1 Like

I've updated the OP with Version 6.0 of Engine.log Tool:

  • If the Command key (⌘) is down when the Done button is selected, added an option to invoke the Terminal command tail -F Engine.log.

  • If this macro is run from another macro using the Execute a Macro action (or via AppleScript), and With Parameter is specified, the following keywords have been added:

    clipboard : bypass the macro dialog box and save the latest failure or timeout to the clipboard

    editor : bypass the macro dialog box and open the Engine.log in a text editor

    reduce : bypass the macro dialog box and go to the Reduce Prompt With List

    reveal : bypass the macro dialog box and reveal the Engine.log in the Finder

    select : bypass the macro dialog box and go to the Failure|Timeout Prompt With List

    tail : bypass the macro dialog box and run the Terminal command tail -F Engine.log

  • Updated the Help window.

I've updated the OP with Version 7.0 of Engine.log Tool:

  • Added a new setting local_DialogVariables : 0|1; default 0 : when the main dialog is displayed, the Time, Action, and Description variables will be included. Note that this value can be toggled by holding the Control key (⌃) when the < Previous, Next >, or Latest button is clicked.

  • Bug fix: If the macro trigger includes the Shift key (⇧), the macro correctly recalls the previously displayed Failure|Timeout. (That feature was broken in Version 6.0.)

1 Like

Since Engine.log Tool can be triggered normally or in 15 alternate modes, Alfred is an ideal method to trigger the macro. For specific information, please refer to this post within a tutorial thread that I had previously shared.

Hello Jim (@_jims) :wave:

This seems to be a very fabulous Macro - and since I am very late to the party and there is nothing mentioned about which Version of KM is compatible my questions are:

Can I use this Macro with Version 10.2 ?!

Or is this Macro unusable for me until I upgrade Keyboard Maestro ?!

Thanks for building such great tools

Greetings from Germany

Tobias

1 Like

Hi, @Nr.5-need_input; I hope you are doing well!

I can’t think of anything in the macro that would prevent it from working with v10.2, but there might be something I’m overlooking. I no longer have access to v10.2, so I cannot test to confirm. If you download and try it, please report back with your observations. Thanks!