Programmatic Specification of Logging

Most logging framework can be constructed through the ini file. However, it is also possible to use Smalltalk code to construct the logging framework as well as to create logging events. This section describes other APIs that may be useful to control what logging events go into a log.

EsLogManager API

The log manager is responsible for the creation and management of the main players: loggers, appenders, logging events and their associated filters. It is the log manager which creates logging events and directs them to a logger.

Creating Logging Events

The following examples illustrate how to create logging events programmatically. The examples below concert the Warn level. There are similar APIs for levels Debug, Error, and Info.

EsLogManager logWarn: 'Help'.

The above code will create an EsLoggingEvent with a level Warn, a message of 'Help', and ask the rootLogger, which always exists, to send it to all its appenders.

You can also ask an existing logger other than the rootLogger to do the logging:

(EsLogManager loggerNamed: 'Vast') logWarn: 'Help'.

The above code will create an EsLoggingEvent with a level Warn, a message of 'Help,' and ask the logger named 'Vast' to send it to all its appenders. This code will do nothing if there is no logger named 'Vast'.

The two examples above will create EsLoggingEvent objects with the className, methodName, and object instance variables set to nil. If you want to log these values, too, use one of the APIs below:

EsLogManager

logWarn: 'Help'

locationInfo: self currentClassAndMethod

object: self.

 

EsLogManager

logWarn: 'Help'

locationInfo: self currentClassAndMethod.

 

EsLogManager

logWarn: 'Help'

object: self.

The EsLoggingEvent object instance variable is probably most useful when set to the object that created the logging event, but you can put any object in it that you want and customize its logging in a printLog4s method on that object's class. See the conversion specifier discussion.

Adding Filters

The following are important messages which an EsLogManager uses create a filter for an existing appender, which determines the requirement a logging event must meet to appear in a log. The appender is then associated with a specific already existinglogger.

The array of strings passed in to the filter creation methods always starts with 1 – logger name, 2 – appender name, 3 - filter name. The filter is returned if it is created successfully, nil if not.

•	classNameFilter anArray: add a filter that allows through log events from a certain class. The filter specific portion of the array takes the form

4 – className To Filter

5 - acceptOnMatch (optional)

Example:

EsLogManager singleton classNameFilter:

#('root' 'Transcript' 'aClassNameFilter' 'Foo' true).

•	levelMatchFilter: anArray add a filter that allows through log events rising to a certain level. The filter specific portion of the array takes the form

4 - level To Filter

5 - acceptOnMatch (optional)

Example:

EsLogManager singleton levelMatchFilter:

#('root' 'Transcript' 'aLevelMatchFilter' 'Warn').

•	addLevelRangeFilter: anArray add a filter that allows through log events within a certain range of levels. The filter specific portion of the array takes the form

4 – first Level

5 – second Level

6 - acceptOnMatch (optional)

Example:

EsLogManager singleton levelRangeFilter:

#('root' 'Transcript' 'aLevelRangleFilter' 'Debug' 'Warn' true).

•	addStringMatchFilter: anArray add a filter that allows through log events containing a certain string. The filter specific portion of the array takes the form

4 - string to match

5 - acceptOnMatch

6 - ignore case

Example:

EsLogManager singleton stringMatchFilter:

#( 'root' 'Transcript' 'aStringMatchFilter' 'Mo' true true).

 

EsLogger API

A logger accepts logging events and collaborates with appenders to direct them to a log. The following are important messages which a logger uses to manage its appenders:

•	addAppender: aNameString creates an EsAppender, or one of its subclasses. Unlike log4j, however, # addAppender in log4s will not create an EsAppender if the EsLogger already has an EsAppender by that name. A successful call will return the added EsAppender, and one that fails will return nil.

•	removeAppender: aNameString will remove an EsAppender if an EsAppender by that name exists on the EsLogger after first calling shutDown on the EsAppender to close any open files. A successful call will return the removed EsAppender, and one that fails will return nil.

•	removeAllAppenders sends the shutDown message to all EsAppenders associated with the EsLogger, and then resets the collection of EsAppenders to empty. The EsLogger will still exist.

•	getAppender: aNameString returns the existing EsAppender by that name or nil if none exists.

•	allAppenders returns all the EsAppenders that belong to the EsLogger.

 

EsAppender API

An appender accepts logging events and directs those that satisfy its requirements to a log. The requirements are expressed as filters and levels.

•	removeFilter: aNameString will remove a filter if a filter by that name exists on the EsAppender.

 

Note

The preferred method of adding a filter to an EsAppender is through the EsLogManager using the filter instance creation methods.See AddingFilters.

 

EsAppender API Examples

 

This section discusses how to create and use the Transcript appender. For examples on how to creat other various types of appenders, see “Redirecting Log Entries”

 

Transcript Appenders are instances of EsTranscriptAppender. The two methods below show how to create an EsTranscriptAppender and how to write to it.

 

"create a transcript appender that will log the message sent along with the date"

| transcriptAppender aString |

 

transcriptAppender := EsTranscriptAppender

level: EsLevel Warn

layout: (EsPatternLayout new: '%d %m').

 

(EsLogManager rootLogger addAppender: transcriptAppender).

 

EsLogManager warn: 'Hi, Mom'.

 

The above example will result in a line in the transcript for the 'warning' message. The transcript will look something like this. The first part of the line is the date and time including the milliseconds; the second part is the warning message itself.

2017-06-07 11:57:57,028 Hi Mom