AjaxAppender

Configures an AjaxAppender.

Definition

<configuration> 
    <jsnlog>
        <ajaxAppender 
            name="string" 
            level="number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL"
            userAgentRegex="regular expression"
            ipRegex="regular expression"
            disallow="regular expression"
            storeInBufferLevel=
                "number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL"
            sendWithBufferLevel=
                "number|TRACE|DEBUG|INFO|WARN|ERROR|FATAL|OFF|ALL" 
            bufferSize="number" 
            batchSize="number" 
            batchTimeout="number" 
            maxBatchSize="number" 
            sendTimeout="number"              
            url="string" />
     </jsnlog>
</configuration>

public class AjaxAppender
{
    public string name { get; set; }
    public string sendWithBufferLevel { get; set; }
    public string storeInBufferLevel { get; set; }
    public uint bufferSize { get; set; }
    public uint batchSize { get; set; }
    public uint batchTimeout { get; set; }
    public string level { get; set; }
    public string ipRegex { get; set; }
    public string userAgentRegex { get; set; }
    public string disallow { get; set; }
    public uint string maxBatchSize { get; set; }
    public uint sendTimeout { get; set; }
    public string url { get; set; }
}

Remarks

An AjaxAppender sends log messages to the server.

Loggers do not process log messages themselves. Instead, they pass them on to an appender. That way, the attributes that have to do with for example sending log messages to the server are centralized, making them more easy to manage.

JSNLog creates a default appender, so there is no need to create one yourself in order to start logging. Details about this default appender, and how to associate JavaScript loggers with appenders, are here.

This element can have the following attributes:

Attribute	Default	Description
name required		Required. Name of the AjaxAppender you want to configure. Must be unique across all appenders.
level optional	TRACE	Numeric or named severity. Only log messages with a severity equal or higher than this can be sent to the server.
userAgentRegex optional	(empty)	If not empty, log messages only get processed if this regular expression matches the user agent string of the browser.
ipRegex optional	(empty)	If not empty, log messages only get processed if this regular expression matches the IP address(es) from which the page was loaded (details below).
disallow optional	(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	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	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	0	Sets the size of the buffer used with sendWithBufferLevel and storeInBufferLevel.
batchSize optional	1	Allows you to improve performance by sending multiple log messages in one go, rather than one by one (details).
batchTimeout optional	(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 (details).
maxBatchSize optional	20	When the server is unreachable and log messages are being stored until it is reachable again, this is the maximum number of messages that will be stored. Cannot be smaller than batchSize (details).
sendTimeout optional	5000	If no response has been received for a log request after this many milli seconds, the outstanding request is aborted and a new request sent with the log messages (details).
url optional	defaultAjaxUrl	See Setting the url to send logs to.

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.

ipRegex

The ipRegex feature lets you switch loggers and appenders on or off depending on the IP address from which the page was loaded. For example, you only want to receive log messages from a live site, but not from a staging site.

For this to work, jsnlog.js on the client has to know that IP address. Options to make that happen:

On the server, set insertJsnlogInHtmlResponses to true in the JSNLog server side configuration. JSNLog will insert JavaScript in the page html going to the browser that sets the IP address.
On the client, call JL.setOptions and pass in the IP address via the clientIP field.

How JSNLog works out the IP address of the page request

When JSNLog works out the IP address where the page request was received (that is, the IP address of the user's browser), this may not be 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.

In that case, the "IP address" is actually a string with a comma separated list of IP addresses. First is the IP address of the browser itself, then intermediate proxies (in the order in which they were reached) and then the IP address of the load balancer if there is one:

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

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 TRACE are ignored.
Log messages with severity equal or greater than TRACE and lower than WARN are stored in the internal buffer, but not sent to the server;
Log messages with severity equal or greater than WARN and lower than FATAL are sent to the server on their own;
Log messages with severity equal or greater than FATAL are sent to the server, along with all messages stored in the internal buffer.

<jsnlog>
    <ajaxAppender 
        name="appender1" 
        storeInBufferLevel="TRACE" 
        level="WARN" 
        sendWithBufferLevel="FATAL" 
        bufferSize="20"/>
    <logger appenders="appender1"/>
</jsnlog>