JSON logging

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

UnrealIRCd 6 introduces optional JSON logging in log files and in server notices sent to snomasks. This makes it easy to parse and process log messages by programs and bots.

JSON Example output[edit]

This is an example of the JSON output when someone connects:

Unreal json example.png

Enabling in disk logging[edit]

Usually you will want to keep your ircd.log logging as plaintext (non-JSON) because it is easy to read by humans.

So just add another NEW log block with JSON logging enabled, like this:

log {
        source {
                all;
                !debug;
        }
        destination {
                file "ircd.json.log" { maxsize 100M; type json; }
        }
}

As you can see, you simply set the log::destination::file::type to json.

And then /REHASH.

Colorized JSON[edit]

The JSON logged to the file is not nicely formatted and does not contain color. The colorized JSON log as shown in the screenshot on this page is generated with the tool 'jq'. So this is all completely optional, just mentioning it for anyone interested in seeing it colorized:

  1. Install jq, eg through: sudo apt-get install jq
  2. Then tail (or cat) the log through it, eg: tail -F ~/unrealircd/logs/ircd.json.log|jq

Enabling on IRC[edit]

IRCOps receive server notices through snomasks. It is possible to receive the associated JSON logging data on IRC as well.

Since this is very new, no client supports this natively, so here is a technical explanation:

  1. Send CAP REQ unrealircd.org/json-log to indicate that you want to receive JSON logging, eg /QUOTE CAP REQ unrealircd.org/json-log
  2. Become IRCOp using /OPER (if you are not one already)
  3. Open up a debug window in your client so you can see raw IRC traffic. Eg: /debug -pt @debug in mIRC. Other clients typically have something similar.
  4. Now when you receive a server notice via snomasks (for example a new user connecting), then the JSON data will be sent in the unrealircd.org/json-log message tag.

In mIRC scripting the JSON data in the server notice will be in $msgtags(unrealircd.org/json-log)

Your bot/program can then parse this as JSON data and process it. The format is much more consistent than regular text messages and typically show a lot more details about the objects involved (client, channel, etc)