JSON logging

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

The JSON log also contains a lot more detail than the text log because it includes, for each user, things like realname, account, operlogin, geoip information, tls information, channels, etc.

If you are a fan of JSON, then you may also be interested in JSON-RPC which allows remotely controlling UnrealIRCd. In UnrealIRCd 6.1.0 and later JSON-RPC also allows real-time streaming of log events over websockets with the log.subscribe API call.

= JSON Example output = This is an example of the JSON log output when someone types :



= Enabling JSON logging = JSON logs can be written to disk, received over IRC or received over websockets via JSON-RPC.

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

So, just add another NEW log block with JSON logging enabled, to for example, 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
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. So this is all completely optional, just mentioning it for anyone interested in seeing it colorized:
 * 1) Install jq, eg through:
 * 2) Then tail (or cat) the log through it, eg:

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

No IRC client supports this natively out of the box, so here is a technical explanation:
 * 1) Send   to indicate that you want to receive JSON logging, eg
 * 2) Become IRCOp using   (if you are not one already)
 * 3) Open up a debug window in your client so you can see raw IRC traffic. Eg:   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   message tag.

In mIRC scripting the JSON data in the server notice will be in

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 shows a lot more details about the objects involved (client, channel, etc)

NOTE: If you use ZNC or another bouncer, then this won't work because it does not pass on the message tag.

Example on IRC
First, request the capability, oper up, and for this example we will also set the join snomask (+s +j): CAP REQ :unrealircd.org/json-log OPER ........... MODE Yournick +s +j

Then when another client types  we will receive the following raw server traffic: @unrealircd.org/json-log={"timestamp":"2022-05-23T11:02:13.519Z","level":"info","subsystem":"join","event_id":"LOCAL_CLIENT_JOIN","log_source":"maintest.test.net","msg":"User\sSyzop\sjoined\s#five","client":{"name":"Syzop","id":"001F9RV02","hostname":"xyz.example.org","ip":"198.51.100.1","server_port":6697,"client_port":37030,"details":"Syzop!~x@xyz.example.org","connected_since":"2022-05-23T11:02:06.000Z","idle_since":"2022-05-23T11:02:06.000Z","user":{"username":"~x","realname":"IRC\sUser","vhost":"oper/netadmin.test.net","cloakedhost":"Mask-8608861.example.net","servername":"maintest.test.net","reputation":12,"security-groups":["unknown-users","tls-and-known-users","tls-users"],"modes":"iotxz","geoip":{"country_code":"NL"},"snomasks":"bcdfkoqsBOS","operlogin":"Syzop","operclass":"netadmin-with-override","channels":["#five","#four","#three","#two","#one"]}},"tls":{"certfp":"aafe66a7d808e1fca077805c54b1274a92d30c3023e35ec130f358d238218296","cipher":"TLSv1.3-TLS_CHACHA20_POLY1305_SHA256"},"channel":{"name":"#five","creation_time":"2022-05-23T11:02:13.000Z","num_users":1,"modes":"ntf\s[4j#R1,5m#M1,3n#N1,3t#b1]:2"},"modes":"o","source":{"file":"join.c","line":292,"function":"_join_channel"}}
 * maintest.test.net NOTICE oper :join.LOCAL_CLIENT_JOIN [info] User Syzop joined #five

With the help of a JSON library the client can then decode it to objects.

Enabling in JSON-RPC
In UnrealIRCd 6.1.0 and later JSON-RPC allows real-time streaming of log events over websockets with the log.subscribe API call.

= UnrealIRCd JSON data = Every JSON log message contains at least the following data:

In addition to that there are a couple of fields that are often included (but not always!):

There are many possible log messages and the additional fields that are available for each event differ. You can look at the List of all log messages for a particular event to see how it is generated. Or you can capture real log items or IRC data.

client object
For JSON logging we use a Detail level of 3 for client objects.

channel object
For JSON logging we use a Detail level of 1 for channel objects. Level 2 and higher are only used by JSON-RPC.

socket_error object
Included in socket errors. Such as a socket being closed due to a network problem or otherwise.

NOTE: The error codes and strings come directly from the OS and C library, hence they will differ between OS's (Linux, Windows, FreeBSD, ..).

tls_error object
Included in SSL/TLS errors. Such as failure to read a certificate file or a socket being closed due to a network problem.

NOTE: The error codes and strings come directly from OpenSSL (outside our control).

link_block object
This is the content of a Link block. It is typically included in server linking errors, but only if it is known which server to link to/from.