JSNLog

Remarks

This element has two sets of attributes:

• Those that apply to JSNLog's client side library jsnlog.js, dealing with loggers and appenders;
• Those that apply to JSNLog's server side component, dealing with CORS and processing of log messages.

Client side attributes

Server side attributes

maxMessages

You use maxMessages to limit the number of messages sent to the server, per page load.

When the page is loaded by the client, 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.

serverSideMessageFormat

Your server not only receives the the original message passed into the JavaScript logger, but also the logger, the level, a timestamp, etc.

You can choose to have this additional information logged on the server along with the original message, by setting serverSideMessageFormat to a format string with one or more place holders:

* If you use Elmah, %newline won't result in a newline in the elmah.axd page, because Elmah doesn't convert line breaks to HTML <br /> tags.

An alternative way to add information to your log messages is writing your own logging event handler. This gives you access to the cookies, request headers and query parameters of the incoming log request. It also allows you stop a message from being logged based on its content.

%message and %jsonmessage

Most people store log messages as unstructured strings of text. If that is you, you can skip this section. However, if you store log messages as valid JSON objects, read on.

Both %message and %jsonmessage are replaced by a string that represents the message that was logged. The difference is that whereas %message is replaced by the log message as-is, %jsonmessage is replaced by a string that can be used in a JSON message.

To clarify the issue, see the table below:

As you see, there is no difference when logging an object (in the second row). But when logging a simple string, %message is replaced by the string, while for %jsonmessage the string is escaped and quoted.

This is important if you want to write valid JSON strings to your log. Suppose you attempted to do that using:

serverSideMessageFormat="{ 'Message': %message }"

That would work well if you only logged objects. But if you logged the string O'Connell, that would result in:

{ 'Message': O'Connell }

Which is not a valid JSON string. However, if you'd use:

serverSideMessageFormat="{ 'Message': %jsonmessage }"

The result would be a valid JSON string:

{ 'Message': "O\u0027Connell" }

serverSideMessageFormat and structured logging

If you create structured logs using Serilog, make sure that your format string results in a valid JSON string. Otherwise it will be logged as a string rather than an object.

Take for example:

serverSideMessageFormat="Sent: %date, Browser: %userAgent, Message: %message"

This will result in a string such as this in your log:

"{ 'Sent': 2014-08-19 21:02:42,603, 'Browser': 'Mozilla/5.0 ...', 'Message': {\"x\":5,\"y\":88} }"

To get a structured object instead, make sure that the result of your format string is a valid JSON string. For example:

serverSideMessageFormat="{ 'Sent': '%date', 'Browser': '%userAgent', 'Message': %jsonmessage }"

Note:

• The curly braces;
• Field names have been quoted.
• %date and %userAgent have been quoted as well, to make them strings.
• %message has been replaced by %jsonmessage, which has not been quoted. That way, when you log objects, they will be logged as objects rather than strings.

This will result in an object such as this in your log:

{ "Sent" : "2014-08-19 21:02:42,603", "Browser" : "Mozilla/5.0 ...", "Message" : { "x" : 5, "y" : 88 } }

Finally, the default value of serverSideMessageFormat gives you structured logging out of the box, even though the default is %message. The reason is that the Serilog adapter that is used by JSNLog to log to Serilog regards all strings that are not valid JSON strings as simple strings that are to be logged as-is.