Documentation Menu

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) of the sender of the request (details below). 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. On the server, you can also use Winston transports (how). 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 appender for use by the root logger.

On the server, the default appender is a ConsoleAppender that logs to the console. On the client, the default appender is an AjaxAppender that sends log messages to the server.

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:

Option Default Value
level TRACE
userAgentRegex (empty)
ipRegex (empty)
disallow (empty)
storeInBufferLevel ALL
sendWithBufferLevel OFF
bufferSize 0
batchSize 1
url defaultAjaxUrl
(only on the client)

Working out the IP address of the sender of a request

Working out the IP address of original sender of an HTTP request (that is, the user's browser) is not as simple as looking at the source address in the request.

If your web server sits behind a load balancer, the source of the final request to the web server is not the browser, but the load balancer. The request may also have been passed on through intermediate proxies, causing the same issue.

The most common (but non-standard) solution to this is that proxies and load balancers (such as AWS' Elastic Load Balancer) send an X-Forwarded-For request header with the IP addresses of the browser and any proxies that the request passed through, except for the final source address. JSNLog uses this request header to work out the IP address of the actual browser and the proxies and/or load balancer that the request passed through.

JSNLog reports the IP address(es) of the sender(s) of the request as a string of text containing a comma separated list. First is the browser itself, then intermediate proxies (in the order in which they were reached) and then the load balancer if there is one:

Browser IP address, Proxy 1, ..., Proxy N [, Load Balancer]

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": [ ]
});