Documentation Menu

setOptions Method

Sets options for an ajax appender.

Definition

setOptions(options: any): AjaxAppender

Parameters

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

Return Value

The AjaxAppender itself.

Remarks

The JSON object can have the following fields:

Field Type Default Description
level
optional
number TRACE Numeric severity. Only log messages with a severity equal or higher than this can be sent to the server.
userAgentRegex
optional
regular expression (empty) If not empty, log messages only get processed if this regular expression matches the user agent string of the browser.
ipRegex
optional
regular expression (empty) 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 (empty) 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.
storeInBufferLevel
optional
number ALL If the severity of the log message is equal or greater than this, but smaller than level, the log message will not be sent to the server, but stored in an internal buffer.

If bufferSize is 0 or less, the log message is simply ignored.

sendWithBufferLevel
optional
number OFF If the severity of a log message is equal or greater than this, not only the log message but also all log messages stored in the internal buffer will be sent to the server.

This allows you to store low priority trace messages in the internal buffer, and only send them when a high priority fatal message is sent.

bufferSize
optional
number 0 Sets the size of the buffer used with sendWithBufferLevel and storeInBufferLevel.
batchSize
optional
number 1 Allows you to improve performance by sending multiple log messages in one go, rather than one by one.
batchTimeout
optional
number (no timeout) Usefull when batching log messages. If set, log messages are guaranteed to be sent within this period (in milli seconds), even if the batch size has not been reached yet.
url
optional
string defaultAjaxUrl All log messages will be sent to this URL. See below.
beforeSend
optional
function (empty) Function called before an AJAX request is sent to the server. Lets you set request headers, etc. See below.

Logger level and appender level

Notice that both loggers and appenders have a level. This means that a log message must have a severity that is equal or higher than both these levels in order to be processed.

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]

beforeSend

The beforeSend field lets you set a function that is called right before an AJAX request with log messages is sent to the server. It receives these parameters:

beforeSend(xhr: XMLHttpRequest, json: any)
xhr XMLHttpRequest object used to send the request. Allows you to for example add your own request headers.
json Message to be sent. Allows you to modify this message before it is sent. See below.

The message passed in via the json parameter has this format:

{
    r:  "request id", // Obsolete. May be empty string.
    lg: [
        { l: level, m: 'message', n: 'logger name', t: timestamp },
        ...
    ]
}

Please note that a single JSON message to the server can contain multiple log messages. This is because the AJAX appender can be configured to batch messages, for example 2 log messages per JSON message to the server.

About the individual fields:

Field Description
request id Obsolete. Do not use.
level Numeric severity of the log message.
message Message to be logged.
logger name Name of the logger.
timestamp The time the message was logged by your JavaScript. This is the number of milliseconds since 1 January 1970 00:00:00 UTC, according to the client machine's clock.

To set a default beforeSend method for all ajax appenders, set the library wide option JL.defaultBeforeSend. An appender's own beforeSend method takes priority over any JL.defaultBeforeSend method.

url

The url that this AjaxAppender sends log requests to. The default url is /jsnlog.logger.

If you send the log requests to a domain different from that of your site (such as logger.mydomain.com/jsnlog.logger), make sure the server side end point where you receive log requests implements the CORS protocol. Otherwise the browser won't send log requests to your end point.

Examples

This creates an appender with the behaviour below and than attaches it to the root logger:

  • It has an internal buffer that stores at most 20 log messages;
  • Log messages with severity smaller than 1000 (TRACE) are ignored.
  • Log messages with severity equal or greater than 1000 (TRACE) and lower than 4000 (WARN) are stored in the internal buffer, but not sent to the server;
  • Log messages with severity equal or greater than 4000 (WARN) and lower than 6000 (FATAL) are sent to the server on their own;
  • Log messages with severity equal or greater than 6000 (FATAL) are sent to the server, along with all messages stored in the internal buffer.
var appender = JL.createAjaxAppender("example appender");
appender.setOptions({
    "bufferSize": 20,
    "storeInBufferLevel": 1000,
    "level": 4000,
    "sendWithBufferLevel": 6000
});

JL().setOptions({
    "appenders": [appender]
});

Create an appender that sends an additional request header "JSNLog-Custom-TestHeader" each time it sends log messages to the server.

var addRequestHeaders = function (xhr) {
    xhr.setRequestHeader('JSNLog-Custom-TestHeader', 'test value');
};

var appender = JL.createAjaxAppender("example appender");
appender.setOptions({
    "beforeSend": addRequestHeaders
});

JL().setOptions({
    "appenders": [appender]
});