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 http://en.wikipedia.org/wiki/Transport_Layer_Security. In certain versions of IE, log events are sent in the clear regardless of configuration due to the constraints of the.

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