Using custom log entry types

Introduction

Application logging is an essential feature to gain understanding into the runtime behavior of an application. Developers can add log messages to their application code to provide details about the application execution or state as needed. While a developer may wish to see a large number of logging messages while developing a new feature, those log messages may not always be required in a runtime environment. Customer log entry types allow developers and application administrators to control which logging messages are written to the client (or AppServer) logfile or an ILoggingStream implementation.

The format of custom log entry types

Custom log entry types do not require to be registered or defined in any way. Developers can just start writing messages to them. Custom log entry types may be used together with a logging level, similar to the logging level used by the built in ABL LOG-MANAGER system handle and the related startup parameters.

The logging level is supported from 0 to 4. 

Logging LevelConsultingwerk.Framework.Enum.LoggingLevelEnumDescription
0NoneNo logging
1ErrorsLog only errors
2Basic (default)Log only basic trace information
3VerboseLog verbose trace information
4ExtendedLog everything

The custom log entry type is basically like a name or identifier of a group of logging messages or the identifier of a component or function providing log messages. The custom log entry type might be defined as:

<custom log entry name> or <custom log entry name>:<logging level>

As an example a custom log entry type might be defined as:

DataAccess or DataAccess:2 (both the same) or DataAccess:4 

Writing log messages under a custom log entry type

The Consultingwerk.Util.LogManager static class or the the Consultingwerk.Util.LoggingStream.ILoggingStream implementations provide a number of methods with an additional parameter to provide the custom log entry type which needs to be activated (with the exact or a higher logging level) to write logging messages to the according output destination. When the custom log entry type is not active (or at a lower logging level), messages that are referenced in the program code will not cause any output. 

There are two ways the logging methods expect the custom log entry type:

1.) As a character parameter, like:

Consultingwerk.Util.LogManager:WriteMessage ("This is a message", "SampleLogEntry:3") . 

2.) Through an instance of the MessageSubSystem class

Consultingwerk.Util.LogManager:WriteMessage ("This is a message", NEW MessageSubSystem ("SampleLogEntry", LoggingLevelEnum:Verbose) . 

Both methods will produce the same logging output. The second variant is required to achieve disambiguation of method signatures - as there are some variants of methods in the LogManager and ILoggingStream classes that expect a sequence of character parameters. 

Activating and deactivating the log output for certain log entry types

Custom log entry types can be activated and deactivated through code - which allows to use a variety of configuration options for custom log entry types. 

/* Enable custom log entry types (enabling logging output) */
Consultingwerk.Util.LogManager:AddCustomLogEntries ("DataAccess:2,SampleLogEntry") .
Consultingwerk.Util.LogManager:AddCustomLogEntries ("SecurityService") .

/* Removing cusotm log entry types (disabling logging output) */
Consultingwerk.Util.LogManager:RemoveCustomLogEntries ("DataAccess:2,SampleLogEntry") .
Consultingwerk.Util.LogManager:RemoveCustomLogEntries ("SecurityService") .

/* Setting the active log entry types */
Consultingwerk.Util.LogManager:CustomLogEntries = "DataAccess:2,SampleLogEntry" .

Querying if a custom log entry is active 

In situations where it may be too expensive to call into a LogManager method or to determine the data for the actual logging output, it's possible to query if a log entry type is active:

IF Consultingwerk.Util.LogManager:IsCustomLogEntryTypeActive ("SampleLogEntry:3") THEN DO:
    Consultingwerk.Util.LogManager:WriteBuffer (BUFFER Customer:HANDLE, FALSE) .
END.

Using the JSON Configuration File to control the custom log entry types used by an AppServer

The JSON Configuration File may be used to configure the custom log entry types used by an AppServer session.