Home

Pages 1

Clone this wiki locally

FireLogger Protocol

Hey you! so you want to implement FireLogger support for your favorite language?

Overview

FireLogger content is sent from server to client via HTTP headers. To be safe it is BASE64 encoded UTF-8 JSON broken into multiple FireLogger headers.

Server can send multiple JSONs in one response, I call it packets. That is why each FireLogger header has hex id which should be assigned by server for every new packet (for example FirePython generates this as random ID).

These are main reasons:

we don’t want to interfere with response content (it may be anything from HTML, javascript, CSS or unknown binary data)

to keep it simple and safe (opening other communication channel with server would be from non-trivial to impossible – you know firewalls and such)

JSON is easy for FireLogger addon (Javascript) and every server-side environment has libraries for serialization into JSON, so no big deal here

Request Headers

You have to take care about incoming request headers in your server side library:

X-FireLogger – presence of this header says that FireLogger is ready to receive your packets, value is FireLogger version

you must emit packets only if you encounter this header

you should warn user if there is version mismatch between your library and FireLogger

X-FireLoggerAuth – authentication token

you should check against this token if you have password to protect server-side

Authentication

The auth token is md5_hex(#FireLoggerPassword#[password]#), of course replace [password] with actual password.

Important log fields:

message – plain log message as it would be logged by your text logger

template – template version of message, arguments should be marked as %X, where FireLogger doesn’t care about X

args – array of arguments to be replaced in template. it is your hard work to provide FireLogger with detailed representation of arguments as structured data so user can drill it down in the Watches window. note: in current example, there is “py/tuple” structure wrapping actual array. This is specific to Python jsonpickle library, FireLogger can unwrap it, but you should send plain array in this case.

level – debug level, one of debug,info,warning,error,exception

timestamp – unix timestamp of log record (sorting)

time – user friendly time to be displayed with log record

name – logger name – see green bubbles on the right of each log record

pathname, lineno – log line location in source file

Other fields are probably not used. These fields are visible to user when he right-clicks on log record and select “inspect in DOM tab” so you can add your own properties if you find it useful.

Exceptions:

In case of exception, FireLogger is able to provide back trace, call stack or call it in whatever you like. It looks like this:

And that’s it!

This protocol has started as a lazy serialization of Python log and exception structures. I know it is not very nice, but who cares? The project started as a quick hack to test if I can do it in a few hours. It worked but it took much more to get into in current state. But protocol stayed Pythonic. I’m open to extend or change this protocol if you need. Good luck.