2.6 KiB
🔥 Packet Logging
For debugging purposes, Ember's gateway allows for all messages to/from a client to logged to file for later analysis. The packet logger is similar in design to the main logger in that allows for attaching multiple 'sinks'. A sink is an object that represents an output destination, e.g. a file, network socket, etc.
Sinks
There are two provided sinks, the LogSink and the FBLog sink. The FBLog sink is the preferred method of packet logging and is intended to be used with Ember's packet conversion utility.
LogSink
LogSink is intended as a quick way to view packet dumps on the terminal during development. As it outputs to the standard logger, it may be configured to output to a remote syslog or file. Packet log entries use a log filter value of 128 (LF_PACKET_LOG).
An example of the output:
[trace] 127.0.0.1:64027 -> CMSG_PING
[trace] [09:04:28] 127.0.0.1:64027, inbound:
0000 dc 01 00 00 01 00 00 00 64 00 00 00 73 6f 6d 65 ........d...some
0010 20 61 73 63 69 69 20 64 61 74 61 43 53 43 42 3f ascii dataCSCB?
0020 df b2 34 bb 34 53 45 bd fa 78 9f df 23 13 c5 6e ..4.4SE..x..#..n
FBSink
FBSink outputs to a binary file intended as an intermediary format that can be used as input to the packet conversion utility, allowing for conversion to other formats, filtering, and live packet monitoring.
The output file is a series of FlatBuffers messages (schemas/packetlog), each prefixed with an eight-byte header comprising two little-endian fields.
uint32_little_endian size; // size of message, excluding header
uint32_little_endian type; // type of message as defined by the schema
After parsing the header fields, the binary data that follows can be interpretted and verified as a FlatBuffer in any language with FlatBuffers support.
FlatBuffers was chosen as a serialisation format as it allows for the packet viewer to easily provide backwards and forwards compatibility in the event of format changes and due to its existing usage in the Spark protocol.
Note that FlatBuffers are not aligned within the dump file.
Packet Conversion Tool
The PCT (src/tools/packetconvert) accepts FlatBuffer-based packet dumps generated by FBSink and prints a summary of the contained packets to the console. The tool can optionally monitor the input source for new packets as they're written by the core.
The long-term goal is to add support for detailed packet analysis, filtering through Lua scripts and a GUI front-end but this requires first adding some form of compile-time reflection to the message definitions used by the server.