setOptions Method

Remarks

The JSON object can have the following fields:

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:

• You log through multiple appenders.
• You buffer trace messages with the appender option storeInBufferLevel.
• You use the batching feature.

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).