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

Page info

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

Encryption

By default, le.js encrypts calls to the 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.

{
    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");