Creating a client for cutelog

As of version 2.0 anyone can easily create a client in any language that sends log records to cutelog. Here's all you need to know to get started.

Connection

To send records you need to connect to cutelog's listen address via a TCP socket. All communication is one-sided, it will never send anything back to the client.

Everything you send to cutelog must start with the payload length encoded as an unsigned big-endian 4 byte integer (also known as unsigned long). For example, if you want to send an empty JSON-encoded log record ({}), this is the data that you should send:

\x00\x00\x00\x02{}

The payload length is 2, so you must include the binary representation of 2 before the payload.

Log record data format

Log records are key-value maps. Each field of the map can be displayed with a column in the logger table. All fields are displayed unchanged in the detail table. There are no required fields, although some fields are special.

Special fields:

• created (or time) ‒ integer or float of a Unix timestamp that gets formatted into the asctime field with the formatting string that's specified in the appearance settings. If not int or float or if formatting fails, then the current local time is used for formatting. If the formatting string is empty, contents of the created field are copied to asctime.
• levelname (or level) ‒ string, gets capitalized. Used to adapt record's appearance and filter records by levels.
• name ‒ string that indicates the name of the subsystem that created the record. Gets split by the period symbol, creating a tree of namespaces. For example, the name MyServer.Database.Cache can be used to separate records that come from only the cache, or from the database and all its "children", or from the server as whole, and so on.
• exc_text ‒ string field that, if not empty, indicates that an exception happened and its traceback (or any other info like that) is included in that field. It can be seen by right clicking on that record and viewing the traceback.

(field names in the parentheses, like msg, are aliases you might want to use instead of the main field name, like message)

Extra mode

There is "Extra mode" in cutelog, which enables intuitive field-centric logging, as opposed to message-centric.

In this mode all extra fields of a record ("extra fields" meaning the ones not already displayed in their own column) appear under the text in the Message column.

This mode isn't suited for Python's logging module (since it includes lots of not-so-useful fields with its records), but it's great for other clients that have relatively small records where every extra field provides important context for the message.

Example:

If your log record is a map like this:

{"name": "MyServer.ReqHandler", "level": "debug", "created": 1528702099, 
 "msg": "User registered", "username": "bob", "id": 13525}

then in extra mode the Message column will look like this:

User registered
username=bob
id=13525

Serialization formats

Out of the box the supported formats are Pickle and JSON, as well as Msgpack and CBOR if they are installed. Pickle is the default (because that's what Python's logging module uses), all other clients can use JSON or others.

You can change the format in 2 ways:

• Change the default in the server settings (thus breaking the Python clients)
• Send an internal command format to cutelog to switch to a different format for that connection

Internal commands

Internal commands are used to control the cutelog logger that the client is connected to. Received data is handled as an internal command only if it starts with !!cutelog!!. Internal commands are key=value pairs, with key being the command.

For example, the command to switch the serialization format for the duration of the connection to Msgpack looks like this: !!cutelog!!format=msgpack (don't forget about the payload length prefix that comes before this whole command payload, which in this case would be \x00\x00\x00\x19)

Supported commands:

• format - changes the serialization format. Supported values: pickle (default), json, as well as msgpack or cbor if installed.

That's it

This is all you need to know. If you're still unsure about something, either contact me or look into gocutelog, it's a small Go package I made that acts as a bridge between existing Go logging libraries and cutelog.