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.
-
local_TextEditorLogEntriesCnt : n; default:500 : maximum number of Engine.log entries that will be opened in the configured text editor
-
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.3
• Sonoma 14.5 (23F79)/MacBookPro18,2
• Sonoma 14.5 (23F79)/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):
-
The output file directory was changed from ~/Desktop to /tmp,
-
setting local_DescendingEntries was dropped and setting local_DescendingIsDefault was added, and
-
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.
8.1 - Per the suggestion of @alltiagocom, included a forum link at the top of the macro. There is no functional change.
9.0
a. Changed occurrences of Cancel This Macro to Cancel Just This Macro. This allows macros that call this macro to continue with further processing once this macro ends.
b. Updated the TESTED WITH section.
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 (647.4 KB)
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.
Console button: Opens the Console application and automatically finds (thus highlights) the failure or timeout that was displayed in the main dialog.
Action button: Opens the Keyboard Maestro application and automatically selects the failure or timeout that was displayed in the main dialog.
Reduce button: Displays the menu of seven methods to reduce the size of the Engine.log.
tail:n (reduce method) ⇨ modify Engine.log, retaining only the latest n entries
purge:RegEx (reduce method) ⇨ modify Engine.log, retaining all entries except those that match the RegEx
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:
-
Download and install Engine.log Tool Macros (link above).
-
Duplicate the macro: Engine.log Tool–21 purge:RegEx
-
Rename the duplicated macro: Engine.log Tool–purge:ABC and XYZ entries silently
-
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.
- For Engine.log Tool–purge:ABC and XYZ entries silently set a Periodic Trigger.
