eligrey/tinylog

A minimalistic logging platform

tinylog is an extensible, yet minimalistic, logging platform.

Getting Started

For the following examples, it is assumed that you upload tinylog to a folder also named tinylog which is relative to the path you are going to use tinylog on.

1. Download tinylog.
2. Include the following code in the page you want to use tinylog on:

   <link rel="stylesheet" type="text/css" href="tinylog/themes/default.tinylog.css" />

3. Also include this following code in the page too:

   <script type="text/javascript" src="tinylog/tinylog.min.js"></script>

4. Optionally include any encoder or decoder scripts if needed.
5. Read the API documentation below.

Supported Browsers

The only officially supported browsers at the moment are as follows. More browsers will be officially supported eventually.

• Google Chrome 4+
• Firefox 3.5+
• Opera 10+

Only browsers that support the W3C File API can use the tinylog viewer app.

tinylog lite

tinylog lite is a bare-bones implementation of tinylog intended primarily for embedding into other libraries. The only API method supported is tinylog.log(). Saving logs is not supported in tinylog lite, and theming must be done directly in the JavaScript code, as opposed to CSS.

Demos

There are live demos you can try out at code.eligrey.com/tinylog.

API

Strong and emphasized text has titles (which can be viewed by hovering your cursor over them) containing their type if they are not functions or return type if they are. Functions are denoted with a suffix of ().

Methods

tinylog.log([message-1], [...], [message-N])

Forwards the messages (concatenated together and separated with spaces) to tinylog.postEntry().

tinylog.postEntry(date, message)

Adds message to the log and with metadata from date. You can easily define your own tinylog.postEntry() method to integrate tinylog into any platform.

tinylog.encode([encodings], [log])

Returns log (defaults to tinylog.entries) encoded using the encoding specified by tinylog.encoding.

  <dt><code>tinylog.<strong title="unambiguous">decode</strong>(<em title="unambiguous">data</em>)</code></dt>

Returns the decoded tinylog array from data.

tinylog.clear()

Clears the log of all output if possible.

tinylog.uninit()

Removes all traces of tinylog from the DOM, including any event listeners.

tinylog.display()

Displays the log.

tinylog.setEncodings(encoding-1, [...], [encoding-N])

Sets the encodings to use when encoding a log. The encodings are applied in order. This is useful for specifying a format encoding and a compression encoding (such as JSON and DEFLATE).

tinylog.setSafetyMargin(safetyMarginPreference)

If the preference is set to true, a margin is set at the bottom of the parent node that can accomidate the full height of the log.

Fields

tinylog.entries

An array of the currently displayed log. It is in the format of [[date-1, message-1], [date-2, message-2], ...].

Configuration

console.TINYLOG

An option that when true, native consoles are not used when available. Otherwise, native consoles will be used if available.

Using Encoders & Decoders

To use an encoding format, call tinylog.setEncodings(), passing it all of the encodings to be used, in order.

Creating your own encoders and decoders is easy! An encoder must return an octet string of the encoded data. The following example implements the built-in JSON encoder and decoders.

tinylog.encoders.JSON = function (log) {
    return unescape(encodeURIComponent(JSON.stringify(log)));
};

tinylog.decoders.JSON = function (data) {
    return JSON.parse(decodeURIComponent(escape(data)));
};

unescape(encodeURIComponent(string)) is a neat trick to encode a UTF-8 string as an octet string. decodeURIComponent(escape(string)) does the opposite, decoding an octet string into UTF-8.

The application/x-tinylog Format

The application/x-tinylog format consists of the following parts, in this order:

• Optional GIF89a\1\0\1\0\x91\xFF\0\xFF\xFF\xFF\0\0\0\xC0\xC0\xC0\0\0\0!\xF9\x04\1\0\0\2\0,\0\0\0\0\1\0\1\0\0\2\2T\1\0;
• Format name
• A line-break
• Log payload

For example, a JSON-encoded log could look like:

JSON
[[1271631583277, "First message"], [1271631585534, "Second message"]]

Formats can encode other formats and be recursively decoded by having the decoder call tinylog.decode().

Theming tinylog

It is very easy to create custom themes using tinylog. Take a look at the default theme to see what classes there are to style.