Provide a Library.SysLog class to allow logging of events while programs are running in a consistent fashion. More...

Static Public Member Functions
_.Library.String	CategoryGet ()
	Return the comma separated list of categories that we log.

	CategorySet (_.Library.String category)
	Comma separated list of categories that we log or null to log all categories.

	ClearLog ()
	Reset the entire log, removing all previous entries. More...

_.Library.Integer	ErrorDetailGet ()
	Return the level to log any <METHOD>LogError</METHOD> events with. More...

	ErrorDetailSet (_.Library.Integer level)
	Set the level to log any <METHOD>LogError</METHOD> events with. More...

_.Library.String	JobGet ()
	Return the comma separated list of jobs that we log.

	JobSet (_.Library.String job)
	Comma separated list of job numbers that we log or null to log all jobs.

_.Library.Integer	Log (_.Library.Integer level, _.Library.String category, _.Library.String message, _.Library.String data, _.Library.String routine)
	Log an event to the system log if the system logging level is greater or equal to the level passed in. More...

_.Library.Integer	LogError (_.Library.String category, _.Library.String message, _.Library.String routine)
	Call this to log an unexpected ObjectScript error. More...

_.Library.Status	LogLevelSet (_.Library.Integer level)
	Set the logging level to one of the following. More...

_.Library.Integer	LogUserInfo (_.Library.String category, _.Library.String username, _.Library.String machinename, _.Library.String exename, _.Library.String IPaddress, _.Library.String routine)
	Log the user information at log level 2 (operational) to category 'UserInfo'. More...

_.Library.Integer	MaxLogEntriesGet ()
	Return the current setting for the maximum number of entries before old ones are killed off.

	MaxLogEntriesSet (_.Library.Integer entries)
	Set the maximum number of entries that this log will hold. More...

	RemoveOldEntries ()
	If there are more than <METHOD>MaxLogEntriesGet</METHOD> in the log then remove any old entries that. More...

Detailed Description

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.

To make logging easier there are three macros defined in occDiagnostics.inc. This file is included automatically when compiling any class and so you only need to include it manually if you are compiling a MAC file. The macros are:

$$$SysLog(level,category,message,data) - If the logging level is greater or equal to 'level' this calls Log^SYS.ISCLOG with the same parameters except 'routine' is set to $ZNAME. If 'data' is an array then pass it by reference
$$$SysLogError(category,message) - If the logging level is greater than zero it will call LogError^SYS.ISCLOG with the same parameters except 'routine' is set to $ZNAME.
$$$SysLogUser - If the logging level is greater than 1 it calls LogUserInfo^SYS.ISCLOG with 'routine' set to $ZNAME and the other parameters coming from $ZU(67)

One of the advantages of these macros is that they check the logging level before calling the <METHOD>Log</METHOD> method and so if logging is not turned on at this level then the log macro takes almost no time to execute.

Member Function Documentation

◆ ClearLog()

ClearLog ( )

static

Reset the entire log, removing all previous entries.

It does preserve setup information.

◆ ErrorDetailGet()

_.Library.Integer ErrorDetailGet ( )

static

Return the level to log any <METHOD>LogError</METHOD> events with.

See

<METHOD>LogError</METHOD> for a description of the levels.

◆ ErrorDetailSet()

ErrorDetailSet ( _.Library.Integer level )

static

Set the level to log any <METHOD>LogError</METHOD> events with.

See

<METHOD>LogError</METHOD> for a description of the levels.

◆ Log()

_.Library.Integer Log	(	_.Library.Integer	level,
		_.Library.String	category,
		_.Library.String	message,
		_.Library.String	data,
		_.Library.String	routine
	)

static

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 InterSystems IRIS or 'IMT' for the InterSystems 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.

◆ LogError()

_.Library.Integer LogError	(	_.Library.String	category,
		_.Library.String	message,
		_.Library.String	routine
	)

static

Call this to log an unexpected ObjectScript 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 <METHOD>ErrorDetailGet</METHOD> and <METHOD>ErrorDetailSet</METHOD> 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

◆ LogLevelSet()

_.Library.Status LogLevelSet ( _.Library.Integer level )

static

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

◆ LogUserInfo()

_.Library.Integer LogUserInfo	(	_.Library.String	category,
		_.Library.String	username,
		_.Library.String	machinename,
		_.Library.String	exename,
		_.Library.String	IPaddress,
		_.Library.String	routine
	)

static

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

◆ MaxLogEntriesSet()

MaxLogEntriesSet ( _.Library.Integer entries )

static

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.

◆ RemoveOldEntries()

RemoveOldEntries ( )

static

If there are more than <METHOD>MaxLogEntriesGet</METHOD> in the log then remove any old entries that.

we no longer need. This is called automatically by <METHOD>Log</METHOD> and <METHOD>LogUserInfo</METHOD> every 10 entries and so you do not normally need to call this manually.

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ClearLog()

◆ ErrorDetailGet()

◆ ErrorDetailSet()

◆ Log()

◆ LogError()

◆ LogLevelSet()

◆ LogUserInfo()

◆ MaxLogEntriesSet()

◆ RemoveOldEntries()