Provide a %Library.SysLog class to allow logging of events while programs are running in a consistent fashion.
The advantage of using this is that we can use standard utilities to manage and display this log. Also all
log entries automatically get the current namespace, date/time, routine name and process Id logged.
One of the advantages of these macros is that they check the logging level before calling the Log
method and so if logging is not turned on at this level then the log macro takes almost no time to execute.
classmethod CategoryGet()
as %String
Return the comma separated list of categories that we log.
classmethod CategorySet(category As %String)
Comma separated list of categories that we log or null to log all categories.
classmethod ClearLog()
Reset the entire log, removing all previous entries. It does preserve setup information.
classmethod ErrorDetailGet()
as %Integer
Return the level to log any
LogError events with. See
LogError for a description of the levels.
classmethod ErrorDetailSet(level As %Integer)
Set the level to log any
LogError events with. See
LogError for a description of the levels.
classmethod JobGet()
as %String
Return the comma separated list of jobs that we log.
classmethod JobSet(job As %String)
Comma separated list of job numbers that we log or null to log all jobs.
classmethod Log(level As %Integer = 2, category As %String = "", message As %String, ByRef data As %String, routine As %String)
as %Integer
Log an event to the system log if the system logging level is greater or equal to the level passed in.
You must specify a
level to log this event at, the choice being:
- 0 - No logging
- 1 - Exceptional events logged, e.g. error messages
- 2 - Detailed event log information, e.g. 'method ABC invoked with parameters X,Y,Z and returned 1234'
- 3 - Raw information logging, e.g. the byte contents of the TCP/IP request sent from the client
The
category is a text field that allows you to subdivide the log entries into various types
you normally pick a name for each application such as 'HTTP' for the in build web server in Cache or 'CMT' for
the Cache Message Transport application. The
message is any text message that you wish to be recorded,
data is any extra data you wish to log.
routine is optional and is the routine name you called from.
Note that
data can be passed by reference and if done it will merge all this information into
a subscript of the log global so you can store large quantities of information if needed.
The return value of this function is the node number where this data is logged or 0 if no log entry was written
typically because the system log level was not set to log an event of the level passed in.
So if you wish to log a problem with a Http request because the Type is wrong while reading it into
the local variable 'request' you could call:
Do ##class(%Library.SysLog).Log(1,"HTTP","Invalid Http request type. Type="_type,request)
Besides the information you pass to the Log method it will automatically log the current date and time
along with the process Id the calling routine name and the current namespace.
classmethod LogError(category As %String = "ERROR", message As %String, routine As %String)
as %Integer
Call this to log an unexpected Cache Object Script error. Pass in the
category to log this
error under, the
message you want reported and the
routine that you are logging the
error from (this is optional). The level of detail the error is logged at is determined by the system wide setting, see
ErrorDetailGet and
ErrorDetailSet to set/get this value. The choices are:
- 0 - Just log the message and the value of $ZE and $ZU(56,5)
- 1 - Log the message, the value of $ZE and $ZU(56,5) and the call stack
- 2 - Log the local symbol table $ZE, $ZU(56,5) and the call stack
classmethod LogLevelGet()
as %Integer
LogLevel
classmethod LogLevelSet(level As %Integer)
as %Status
Set the logging level to one of the following
- 0 - No logging
- 1 - Exceptional events logged, e.g. error messages
- 2 - Detailed event log information, e.g. 'method ABC invoked with parameters X,Y,Z and returned 1234'
- 3 - Raw information logging, e.g. the bytes comming from the Http request
classmethod LogUserInfo(category As %String, username As %String, machinename As %String, exename As %String, IPaddress As %String, routine As %String)
as %Integer
Log the user information at log level 2 (operational) to category 'UserInfo'. If any of username
or machinename or exename or IPaddress are blank or missing then they
default to the values setup in the partition in $ZU(67,n,$J). You normally call without any parameters
at the start of your application to log the person using this job, but you can override the value from $ZU(67)
is you need to. If category is blank it defaults to "UserInfo". routine is the optional
routine you are logging this from, if not specified it defaults to the value found from $Stack($Stack-1,"PLACE").
classmethod MaxLogEntriesGet()
as %Library.Integer
Return the current setting for the maximum number of entries before old ones are killed off.
classmethod MaxLogEntriesSet(entries As %Library.Integer)
Set the maximum number of entries that this log will hold. If this is not set it defaults to 5,000 entries before
it starts removing old entries.
classmethod RemoveOldEntries()
If there are more than
MaxLogEntriesGet in the log then remove any old entries that
we no longer need. This is called automatically by
Log and
LogUserInfo every
10 entries and so you do not normally need to call this manually.