setOptions Method

Sets options for a logger

Definition

setOptions(options: any): Logger

Parameters

options	A JSON object with options. See the Remarks sections below.

Return Value

The Logger itself.

Remarks

The JSON object can have the following fields:

Field	Type	Default	Description
level optional	number	(inherited from parent logger)	Numeric severity. Only log messages with a severity equal or higher than this can be sent to the server.
userAgentRegex optional	regular expression	(inherited from parent logger)	If not empty, log messages only get processed if this regular expression matches the user agent string of the browser.
ipRegex optional	regular expression	(inherited from parent logger)	If not empty, log messages only get processed if this regular expression matches the IP address(es) from which the page was loaded. If you use this, be sure to set the IP address via the setOptions method of the JL object.
disallow optional	regular expression	(inherited from parent logger)	If not empty, log messages are suppressed if they match this regular expression. If an object is being logged, it is converted to a JSON string, which is then matched.
appenders optional	array of appenders	(inherited from parent logger)	One or more appenders for the logger to send its log messages to. See the examples.
onceOnly optional	array of strings	(inherited from parent logger)	One or more regular expressions. When a message matches a regular expression, then any subsequent messages matching that same regular expression will be suppressed. See the remarks and examples.

Logger names and option inheritance

JavaScript loggers not only get their options through the setOptions method, but also through inheritance. This is based on the name of each logger.

Assume that you have a method "method1" in a namespace "namespace1". Then it would make sense to use a naming scheme for your loggers like this: "namespace1.method1.logger1", "namespace1.method1.logger2", etc. This way, there are no name clashes and it makes keeping track of your loggers easy.

Just as a namespace may contain methods, and a method may contain JavaScript loggers, so you can think of these logger names as making up a hierarchy:

The parent of "namespace1.method1.logger1" is "namespace1.method1";
The parent of "namespace1.method1" is "namespace1";
The parent of "namespace1" is the root logger (the logger without a name).

You're not limited to just 3 levels, you can have as many as want.

If you don't set an option using the setOptions method, the logger inherits that option from its parent. If you do not use the setOptions method at all, every JavaScript logger will have the same options as the root logger.

Root logger and default appender

When the library loads, it creates the root logger. It also creates a default AjaxAppender for use by the root logger.

Because every logger inherits from the root logger (unless you override this with the setOptions method), you can start logging right away without having to create an appender.

The root logger is created with these options:

Option	Default Value
level	DEBUG
userAgentRegex	(empty)
ipRegex	(empty)
disallow	(empty)
appenders	(default appender)

Note that because the default level for root logger is DEBUG, by default only log messages with severity DEBUG or higher get processed.

You can change the options used with the root logger in the same way as any other logger, using the setOptions method. See the examples below.

The default appender is created with these options (description of options):

Option	Default Value
level	TRACE
userAgentRegex	(empty)
ipRegex	(empty)
disallow	(empty)
storeInBufferLevel	ALL
sendWithBufferLevel	OFF
bufferSize	0
batchSize	1
batchTimeout	(no timeout)
url	defaultAjaxUrl

Suppressing duplicate messages with onceOnly

You may have JavaScript loggers inside code that gets called multiple times. As a result, you may get a series of messages that are essentially the same. Using onceOnly, you can suppress the duplicate messages, so only the first message is sent to the server.

This works by setting one or more regular expressions. When a log message matches one of the regular expressions, the logger remembers that there has been a message that matched that regular expression. Then when another message arrives that matches that same regular expression, it is suppressed.

For example, if you receive these messages:

    Parameter x too high - x = 5
    Parameter x too high - x = 6
    Parameter x too high - x = 7
    ...
    Parameter x too high - x = 49
    Parameter x too high - x = 50

Then you can use the regular expression:

    Parameter x too high - x =

To only receive the very first message:

    Parameter x too high - x = 5

See the examples for how to set the regular expression.

You can set multiple regular expressions. These work independently. So if a message matches the first regular expression, then if a second message matches the second regular expression but not the first, then the second message gets through because it is not a duplicate of the first message.

As shown here, you can log not only strings but also objects. If you log an object, the object is translated to a JSON string. That string is than matched against the regular expressions.

Similar to other attributes, JavaScript loggers inherit onceOnly from their parents. However, this is all or nothing. If you set onceOnly regular expressions for a logger, than any onceOnly regular expressions that its parent may have had are disregarded.

Examples

This sets the level of logger "a.b" to 3000.

var logger = JL("a.b");
logger.setOptions({
    "level": 3000
});

This sets the level of the root logger.

var rootlogger = JL();
rootlogger.setOptions({
    "level": 3000
});

This sets the level of JavaScript logger "a.b" to INFO (which is the same as setting it to 3000). This code shows you don't need to use the variable logger.

JL("a.b").setOptions({
    "level": JL.getInfoLevel()
});

This sets the level of logger "a.b" to OFF, so it is completely switched off.

JL("a.b").setOptions({
    "level": JL.getOffLevel()
});

This sets the level to 4000. It also disables the logger for all browsers, except those whose user agent string contains MSIE 7|MSIE 8 (that is, it is version 7 or 8 of Internet Explorer).

var logger = JL("a.b");
logger.setOptions({
    "level": 4000,
    "userAgentRegex": "MSIE 7|MSIE 8"
});

This creates an appender "appender" and then tells the logger "a.b" to send all log messages to it.

var appender=JL.createAjaxAppender('appender');
var logger = JL("a.b");
logger.setOptions({
    "appenders": [appender]
});

This creates an AjaxAppender and a ConsoleAppender and then tells the logger "mylogger" to send all log messages to them both.

var ajaxAppender=JL.createAjaxAppender('ajaxAppender');
var consoleAppender=JL.createConsoleAppender('consoleAppender');
JL("mylogger").setOptions({"appenders": [ajaxAppender,consoleAppender]});

Suppress duplicate messages that match the regular expression "Parameter x too high - x =".

JL("a").setOptions({
    "onceOnly": [ "Parameter x too high - x =" ]
});

Suppress duplicate messages that match the regular expression "Parameter x too high - x =". Also suppress duplicate messages that match "x = \d+ and y = \d+".

JL("a").setOptions({
    "onceOnly": [ "Parameter x too high - x =", "x = \\d+ and y = \\d+" ]
});

JavaScript loggers inherit onceOnly from their parents. Assume you have a logger "a.b" whose parent "a" suppresses duplicates, but you want logger "a.b" to not suppress duplicates. To make that happen, give it a onceOnly collection without any regular expressions:

JL("a.b").setOptions({
    "onceOnly": [ ]
});