Tip of the day: If you want to bypass access checks for channels as an IRCOp, use SAMODE or SAJOIN. Or use OperOverride.

JSON-RPC:Log

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

The log.* JSON RPC calls allow you to subscribe and unsubscribe to log events (real-time streaming of JSON logs).

This functionality only exists in UnrealIRCd 6.1.0 and later

API Calls

log.list

Fetch past log entries (since boot).

In UnrealIRCd 6.1.1 and higher the past 1000 log events since boot are logged in a memory buffer. These can be fetched via the log.list RPC call.

Request arguments

There are no mandatory request arguments.

Optional arguments:

  • sources: an array of log sources. See log block sources. For example ["connect"] will give only client connects/disconnects.

IMPORTANT: By default the logs that are kept in the log buffer for log.list has some events filtered out. The following events are not logged in the buffer: debug, join, part, kick. The reason these are already filtered out is because they can generate a lot of events and they are also filtered out in the default example.conf for ircd.log as well, so this makes sense.

Response

The response is a list which is an array of JSON logging events.

log.subscribe

Subscribe to one or more log sources. Any previous subscriptions are overwritten (lost).

Request arguments

Mandatory:

  • sources: an array of log sources. See log block sources. For example ["!debug","all"] would give you all log messages except for debug messages. And ["connect"] would give only client connects/disconnects.

Response

Returns true on success.

After this UnrealIRCd will start streaming log events to you using notifications (if they match your specified sources) until you call log.unsubscribe or disconnect.

Notifications

The log streaming uses JSON-RPC notifications. These look similar to JSON-RPC response messages except that they contain no id. The method will be set to log.event.

The result will contain JSON log entry. You can also check the List of all log messages for full details on specific log messages.

An example of a log event notification is:

{"jsonrpc": "2.0", "method": "log.event", "result": {"timestamp":"2022-05-23T11:02:13.519Z","level":"info","subsystem":"join","event_id":"LOCAL_CLIENT_JOIN","log_source":"maintest.test.net","msg":"User Syzop joined #five","client":{"name":"Syzop","id":"001F9RV02","hostname":"xyz.example.org","ip":"198.51.100.1","server_port":6697,"client_port":37030,"details":"[email protected]","connected_since":"2022-05-23T11:02:06.000Z","idle_since":"2022-05-23T11:02:06.000Z","user":{"username":"~x","realname":"IRC User","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 [4j#R1,5m#M1,3n#N1,3t#b1]:2"},"modes":"o","source":{"file":"join.c","line":292,"function":"_join_channel"}}}

This example was a LOCAL_CLIENT_JOIN entry. For full details on that you go to List of all log messages and then CTRL+F on LOCAL_CLIENT_JOIN. Be sure to also read the How to use this list for JSON data introduction on that page, which will explain what log_data_client() and log_data_channel() are and show the contents of various objects (client, channel).

log.unsubscribe

Unsubscribe from all log events.

Request arguments

None

Response

Always returns true

After this UnrealIRCd will stop streaming log events to you.