[UserLog] Depending on mode, writes one or more of Log, Notify or Alert

Macro Library
1

Title: [UserLog] Depending on mode, writes one or more of Log, Notify or Alert

Code ONE call to the UserLog macro, instead of say Notify action:-

image
image826×239 31.6 KB

Sample output in UserLog file

image
image1604×260 164 KB

Version and Last Update: 26/05/2020 20:08:03 V1.00

Written by: Jonathon Lewys ©2020
Acknowledgements: Peter N Lewis and the Keyboard Maestro Forum.
Disclaimer: Caveat Utilitor applies. See Version History for explanation

Summary: Depending on mode, write one or more of Log, Notify or Alert messages.

Macrogroup:
JGLp [UserLog] Depending on Mode, write one or more of Log, Notify and Alert messages]

HotkeyCombos: Only for palette group and help.

Dependencies
None outside its own macro group

Test environment: Keyboard Maestro 9.05 and Mojave

Components:
00 Display Palette of Macros in this macro group
11 Write the log/notify/alert message (The heart of the system)
90 Set the User RUNMODE, displays help and acts as test harness
91 Display all significant variables used (used in debugging).

Installation notes and Customisation:
(All customisation variables are named: Cuz
Path to UserLog directory
(default = KM Log directory= ~/Library/Logs/Keyboard Maestro)

Number of lines per UserLog before starting a new one (MsgLineCountMax)

Error code prefix - currently Err.
Error code suffix - currently .YOUR initials
Error code format either INFERR or STANDARD or DEBUG

Quick start guide.

Use the test harness (90) to create some error messages and then look at the log file created.

=====================================================
Description

This set of macros had three objectives

A: to notify the user with a meaningful error message if something went wrong
B: for the developer to add debug and testing messages, that could be left in situ when the macro went into production
C: for the support person to be able to quickly identify the error message and take the appropriate corrective action

This macro can do the following:-

A: write a meaningful message to a new UserLog file and/or the KM Engine log file
and/or
B: display a meaningful message via the notify action
and/or
C: raise an alert with a meaningful error message.

Operationally i.e. what is theRUNMODE?
The user/developer is running the computer in one of three modes
A: Production
B: Testing
C: Debug
This operational mode is known as the RUNMODE, and can be changed at any time by setting a Global variable to P or T or D. (UserLog_RunMode_s)

The Error message.
The error message that is written to the log or the notify or the alert is constructed as follows in one of two styles

The default format is

[Timestamp][Error mode] [nnn] Err.e[eee.ss].e[Author/System] Error text

and, alternatively, in my preferred format as

[Timestamp][Error mode] [nnn] [INF or ERR or SEV or DBG]nnn.SS.e[Author] Error text

If format is set to DEBUG, then the macro variables used will be displayed at the end i.e. last step of the macro.

The term MacroActionMode and ErrorMode are the SAME thing.

So the eError mode is P or T or D
[Nnn] says what action to take(see below}
Eee is the error number assigned by developer
Author/System is the name of the developer or system
Error text is free format but should not contain any commas

Runmode and Error mode
Runmode is the mode of operation of the computer
Errormode/MacroActionmode is decided by developer to indicate as follows

If the Runmode is P then only messages with Error mode of e P will be actioned
If the Runmode is T then only messages with Error mode of e P or T will be actioned
If the Runmode is D then only messages with Error mode of e P or T or D will be actioned

So when looking at the macro source, it it is very easy to see in the macro code whether an error message is for Production or Testing or Debugging.

The nnn will be covered below

Errorcode
The error message written to the Log or displayed is constructed as
Err.eee.SS.AA and is displayed as [………….]
Err. Can be customised (Prefix)
Eee.SS is down to the developer, e.g. 101.KM, or 203.UL
Finally AA is the Author of the system. (Suffix). Can also be changed.

In my preferred format, it is
INF.nnn.SYS.AAA

What action to be taken. nnn explained.

The nnn is a set of three octal digits. 0-7. (like Unix permissions).
Each of them is better represented by ptd, where p is the first octal digit.
t and the second and third..
They represent the action to be taken as follows

000 - no action
Xx1 - write a log message
X1x - create a notify message
1xx - create an alert

So a production message might be

P1td, just write a log message
P0td, do nothing
P3td - write a log message and notify
P7td - write a log message, notify and alert

T and D are based on exactly the same principle

BUT
“t” is used if the RUNMODE is T
“d” is used if the RUNMODE is D

This is best explained by way of an example

I have a macro step in Production so I could code it as

P111 - In production mode, just log message, AND in Test or Debug mode do the same

P133 - In production mode, just log message, BUT in Test or Debug mode do BOTH log and notify

T337 In production mode, ignore it as it is a Test message (first 3 is also ignored)
If RUNMODE = Test, then using the second 3, so log and notify
If RUNMODE = Debug, then using the third digit (7), log, notify and alert.

D777
In RUNMODE = Prod, then using First 7 log, and notify and alert.
In RUNMODE = Test, then using Second 7, log and notify and alert.
If RUNMODE = Debug, then using Third 7 , log and notify and alert.

So to summarise

If the run mode is P only do P messages and use first octal
If the run mode is T only do P and T messages and use second octal
If the run mode is D do P, T and D messages and use third octal

If the octal is

000 do nothing
xx1 do log
X1x do notify
1xx do alert

Most of the time the codes will be

P111
P133
T333
T377
D777

This coding scheme means you can leave the macro in place in the code, and it will only execute depending on the RUNMODE value.

Alerts from within this program/macro

UserLog ERR.301.UL.JGL as chars 1,2 are not SP/ST/SD
UserLog ERR.302.UL.JGL Fifth char should be a comma, check param format
UserLog SEV.901.UL.JGL Runaway macro, called too many times
UserLog SEV.911.UL.JGL as chars 234 are not octal [0-7]

NB The macro will STOP if too many messages are wrtten too quickly.

JGLp [UserLog] Depending on Mode, write one or more of Log, Notify and Alert messages Macros v1 _00 .kmmacros (194.6 KB)

2

@jonathonl, you have done an impressive amount of work here, but I'm not sure I understand the end-user use case, nor how to use your system in the real world.

May I suggest a video that shows how you setup and use your system, expecially for case "A" above.

I am especially unclear on the following:

  1. Is your system triggered automatically whenever any macro encounters an error?
  2. If not, how do we use in a our Macros to trigger when a macro error occurs? How do we trap for errors.

One tip: I'd recommend use of the Forum Markdown code to format and organize your descriptions. For the most part, the Forum uses standard Markdown.

3

Thank you for the compliment. I have edited the post to make it clearer I hope.

NO my system does not trap errors.
The idea is that where you would have coded a log,notification or alert action,

you replace THAT action

with a call to my UserLog macro, which would have as its parameter the usermessage you want written to the log.

Example.
Instead of coding a notify as part of a debug, you code a call to the UserLog macro with the information you need to see. It is then easy to turn on/off the debug statement.

4

I second this, a video would be very helpful to see it in action. I appreciate posts like this and no doubt I could use what they have to offer. I often have to remind myself what is in my head is not in other people's head when I am teaching people on computers. Thanks again for the post.