Documentation Menu

setOptions Method

Sets library wide options

Definition

setOptions(options: any): void

Parameters

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

Remarks

The JSON object can have the following fields:

Field Type Default Description
enabled
optional
bool true If false, all loggers are disabled.
maxMessages
optional
number no maximum Limits total number of messages sent to the server. See remarks below.
defaultAjaxUrl
optional
string (empty) See Setting the url to send logs to.
clientIP
optional
string (empty) The IP address of the browser. Used with the ipRegex option of loggers and appenders.
requestId
optional
string (empty) Sent with all log messages to the server, so make it easier to identify all log messages for a given request.
defaultBeforeSend
optional
string (empty) Function called before a log request is sent to the server by all Ajax Appenders. Lets you set request headers, etc (details).
serialize
optional
string see remarks Method used to turn objects into strings. See remarks below.

maxMessages

You use maxMessages to limit the number of messages sent to the server.

When you set maxMessages via a call to setOptions, a counter is set to maxMessages. Each time messages are sent to the server, that counter is decremented by the appender by the number of log messages sent. When the counter gets to zero or below, no more messages will be sent.

This can lead to unexpected behaviour if:

Logging through multiple appenders

As you saw, the counter is decreased by the appender. This means that if you associate a logger with 2 appenders, each time that logger sends a message, the counter is decreased twice (once by each appender).

The counter is decreased by the appender and not by the logger, because:

  • If you have multiple appenders sending messages to the same server, decreasing the counter per appender more accurately limits the load to your server.
  • Only the appender knows whether a message will actually be sent, or if it gets stored in a buffer due to its storeInBufferLevel option.

Buffering trace messages

Take a situation where maxMessages was set to 5 and 2 messages have already been sent - so the counter is now 3. Also, 8 trace messages are stored in the buffer.

If a high severity message is logged causing the trace messages to be sent as well, 1 + 8 = 9 messages will be sent. So the server has now received 2 + 9 = 11 messages. After that, no more messages will be sent, because the number of messages sent (11) exceeds maxMessages (5).

Trace messages are allowed to go over the maxMessages limit, because:

  • This way you don't miss out on trace messages that may help you solve an exception in your JavaScript.
  • The number of excess messages is limited by the size of the trace messages buffer, as set in the appender option bufferSize.
  • The trace messages are sent in a single log request to the server, minimizing bandwidth.

Using the batching feature

Lets assume that:

  • You set the appender option batchSize to 5, so each log request to the server will have up to 5 log messages.
  • You are not using a batch timeout (appender option batchTimeout).
  • There are 2 messages in the batch buffer, so only after 3 more have been added will the entire batch be sent.
  • However, only 1 more message can be accepted before maxMessages is reached.

To make sure that the 2 messages already in the batch buffer are not stranded, next time a log message is generated, the appender will see that this is the very last message that will be sent, and send a batch with the last 2+1=3 log messages.

However, if you use multiple appenders, the appender dealing with the very last message won't tell the other appenders to flush their batch buffers, creating the potential of stranded messages. This is one of the perils of using maxMessages in conjunction with multiple appenders.

maxMessages relates to log messages, not to log requests

If you use log message batching, keep in mind that maxMessages relates to the individual log messages going to the server, not to the number of log requests to the server.

serialize

When you log an object, it needs to be turned into a string. This field lets you set the method used to do this.

If you do not set this field, by default the standard method JSON.stringify is used.

Your method has to take the object as a parameter and return the string:

serialize(object: any): string

A major reason to use your own method is to deal with objects with cyclic references. That is, objects that refer to themselves (details).

Examples

This sets the requestId to be sent with all log messages to the server.

JL.setOptions({
    "requestId": "35F7416D-86F1-47FA-A9EC-547FFF510086"
});