API

Setup

init()

You must call init to set up le.js. At a minimum you must specify a token:

LE.init('YOUR-LOG-TOKEN');

you can also change the default parameters:

Option	Description	Default	Example
token	Mandatory. The Logentries log token	N/A	LE.init('TOKEN') or LE.init({token: 'TOKEN'})
ssl	Use SSL/TLS to send events. See encryption	true	LE.init({token: 'TOKEN', ssl: false})
catchall	Log any uncaught JavaScript exceptions. This replaces the window.onerror handler, but if you've specified one already, it'll invoke that one afterwards	false	LE.init({token: 'TOKEN', catchall: true})
trace	Adds a randomly generated trace code	true	LE.init({token: 'TOKEN', trace: true})
no_format	Sends events to logentries verbatim.	false	LE.init({token: 'TOKEN', no_format: true})
page_info	Append basic information about browser capabilities. Options are never, per-page and per-entry. See page info	'never'	LE.init({token: 'TOKEN', page_info: 'per-page'})
print	Echo events to the screen via the console object. This will logged at the same level as the call to LE, e.g. LE.warn(msg) => console.warn(msg). See log levels	false	LE.init({token: 'TOKEN', print: true})

Tracing

When logging on the web, you don't have any knowledge of the event-generators (browsers!) ahead of time. This presents a problem: how do you group events that originated from the same user-agent, and how do you differentiate users? Even if you have their IP address, that's not a strong guarantee of uniqueness.

The trace_code option adds a string that's unique to each user-agent, giving you a handle to search against in the Logentries dashboard.

Encryption

By default, le.js encrypts calls to the Logentries service with TLS. In certain versions of IE, log events are sent in the clear regardless of configuration due to the constraints of the XDomainRequest specification. Specifically, if the page was served via plain http, log data will be as well.

Page info

le.js optionally lets you log basic capabilities for the originating user-agent. The data sent will look something like this:

{
    name: "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_4; en-us)",
    screenWidth: 1024,
    screenHeight: 768
}

You can choose to send this at the following frequencies:

• per-page: the first time an event is logged after a page refresh
• per-entry: every time an event is logged
• never: not at all

Logging

With le.js configured, go log some events. log takes most of the same arguments as console.log:

log()

LE.log("Hello, logger!"); // Simple string-literal

var x = "logger";
LE.log("Hello, ", x, " and some objects: ", 1); // Interpolation

LE.log({hello: "logger!"}); // Object (gets logged as a key=value pair)

// An object with some nesting
LE.log({nested:
    {object: [1,null],
     key: undefined}
});
// => nested.object.0=1,nested.object.1=null,nested.key=undefined

Format

• Simple JS types (numbers, string literals and booleans) are left untouched
• undefined values will be explicitly printed as strings for clarity (unlike, say, JSON.stringify())
• Objects and arrays are 'flattened' to make them searchable; see the examples above
• Instead of failing on the client, cyclic objects are replaced with a placeholder so they can be serialized. For example:

var x = {}
x.y = x;

LE.log(x) // => {y: '<?>'}

Log levels

le.js supports the following methods to log events at different severity levels:

• log
• info
• warn
• error

They otherwise behave exactly the same as log():

LE.log("a LOG level event");
LE.info("an INFO level event");
LE.warn("a WARN level event");
LE.error("an ERROR level event");

Ad blockers

If you find that the script or its requests are blocked by ad blockers, you can load the script from your own domain and proxy the requests (which look like https://js.logentries.com/v1/logs/94e2188b-506a-40cd-8601-9be0f40ede27) through your own domain as well, using the LEENDPOINT global option. Here's how:

window.LEENDPOINT = window.location.host + '/le/v1';  // in LE: _endpoint = (_SSL ? "https://" : "http://") + _endpoint + "/logs/" + _token;
LE.init({ ...});

In your web server's config, you need to proxy /le/... to js.logentries.com/.... Here's an example for nginx:

# Proxy Logentries
location /le/ {
    rewrite ^/le/(.*)$ /$1 break;  # remove the '/le' part from the path, leaving /v1/logs/xxxxxxxx-xxxx-...
    proxy_set_header Host js.logentries.com;
    // unfortunately, none of the proxy headers are interpreted correctly
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_pass https://js.logentries.com;
}

Unfortunately, this endpoint used in the above example, 'js.logentries.com', sets the parameters as default and ignores any extra parameters parsed with the LE.init().

To use these params, you should send the messages to 'webhook.logentries.com/noformat/logs'

with this set up:

window.LEENDPOINT = window.location.host;  // in LE: _endpoint = (_SSL ? "https://" : "http://") + _endpoint + "/logs/" + _token;
LE.init({ ...});

example for nginx:

 # Proxy Logentries
    location /le/ {
            root /data/www;
            rewrite ^/(.*)$ /$1 break;
# remove the '/le' part from the path, leaving /v1/logs/xxxxxxxx-xxxx-...
            proxy_set_header Host webhook.logentries.com/noformat/logs;
# unfortunately, none of the proxy headers are interpreted correctly
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_pass http://webhook.logentries.com/noformat/logs;
    }

Unfortunately, LogEntries doesn't parse the proxy headers correctly, and all logged data will appear as if it came from your proxy server. Vote for issue #50 to have this fixed.