Need better doc of "FlightRecorder" mode...

[puniverse]

Need better doc of "FlightRecorder" mode...

[pron]

Well, it's an internal API and not "officially supported", intended for debugging concurrency, but let me describe it here anyway.

FlightRecorder is an in-memory log. For every thread there is a cyclical buffer to which records are written with timestamps (so as not to introduce any contention among threads). When the recorder is dumped, the threads' recorders are merged based on their timestamps.

The records are turned into strings only when the recorder is dumped, so when recording mutable objects, the wrong values might be dumped. If that's the case, an object may implement co.paralleluniverse.common.monitoring.RecordingDouble, that returns a cloned, immutable object. If a RecordingDouble is found in the record, its double is recorded.

When recording is turned on, all messages sent or received on channels or actors are recorded, as well as lots of internal values. Recordings are made with a "level" – the higher the level, the more detailed the recordings. For most purposes, turning on recording at level 1 is more than enough.

To turn on recording, the following system properties are used:

• "co.paralleluniverse.debugMode" – must be set to "true" for recording to work.
• "co.paralleluniverse.globalFlightRecorder" – should be set to "true".
• "co.paralleluniverse.monitoring.flightRecorderLevel" – the recording level. "1" is enough.
• "co.paralleluniverse.monitoring.flightRecorderSize" – the size (in records) of each thread's buffer.
• "co.paralleluniverse.flightRecorderDumpFile" – the name of the default dump file

When a program running in debug mode terminates, the flight recorder is automatically dumped to the default dump file (gzipped).

You can programmatically dump a recording with co.paralleluniverse.common.util.Debug.dumpRecorder(), in which case the default file will be used, or you can supply a different name with dumpRecorder(String filename) (in any case, the file will be gzipped and a .gz extension will be added). You can also schedule a dump with dumpAfter(long millis)/dumpAfter(long millis, String filename).

You can also manually dump a recording while the program is running using VisualVM. There's a flight-recorder bean with a dump operation.