MACRO: Engine.log Tool, v7.0

Main Dialog

Help Displayed

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


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.

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_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.)


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 (513.1 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.2 (23C5055b) PRE-RELEASE SEED SOFTWARE
  • Keyboard Maestro v11.0.2

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

1


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

2


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

3


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

4


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

5


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

6


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.
10 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!