docs/howto/monitor-debug-gui.md

0001 ### JANA2 Status/Control Monitoring and Debugging GUI <!-- {docsify-ignore-all} -->
0002
0003 ![JANA Status Control GUI](../_media/JANA_Status_Control_GUI.png)
0004
0005 A very basic GUI program is included with JANA2 to help with monitoring and debugging JANA2 applications.
0006 The JANA2 process that is to be monitored/debugged can be
0007 running on either the local node or a remote node. For this to work, the following criteria must be met:
0008
0009 1. JANA must have been compiled with ZEROMQ support. (This relies
0010    on cmake find_package(ZEROMQ) successfully finding it when camke
0011    is run.)
0012
0013 2. The python3 environment must me present and have zmq installed.
0014    (e.g. pip3 install zmq)
0015
0016 3. The JANA process must have been started with the janacontrol plugin.
0017    This should generally be added to the *end* of the plugin list
0018    like this:
0019
0020 ```
0021 jana -Pplugins=JTest,janacontrol
0022 ```
0023
0024 To start the JANA control GUI, just run the `jana-control.py` program:
0025
0026 ```
0027 jana-control.py
0028 ```
0029
0030 By default, it will try to attach to port 11238 on the localhost. It
0031 does not matter whether the JANA process is already running or not.
0032 It will automatically connect when it starts and reconnect if the process
0033 is restarted.
0034
0035 The following command line options are available for `jana-control.py`:
0036
0037 <pre>
0038 -h, --help     Print this Usage statement and exit
0039 --host HOST    Set the host of the JANA process to monitor
0040 --port PORT    Set the port on the host to connect to
0041 </pre>
0042
0043 n.b. To set the port used by the remote JANA process set the
0044 jana:zmq_port configuration parameter when that process is started.
0045 For example:
0046
0047 ```
0048 jana -Pplugins=JTest,janacontrol -Pjana:zmq_port=12345
0049 ```
0050
0051 Debugger
0052 --------------
0053
0054 The `Debugger` GUI here is really just a browser. It does not allow
0055 for true control flow debugging. For that, please look at the command line
0056 debugger features of JANA2. This is intended to give a way to step
0057 through events and examine the exposed data members of the objects
0058 created in the event.
0059
0060 To open the Debugger window, just press the button in the lower
0061 right hand coner of the control window.
0062
0063 ![](images/JANA_Debugger_GUI.png)
0064
0065 The GUI can be used to step through events in the JANA process and
0066 view the objects, with some limitations. If the data object inherits
0067 from JObject then it will display fields obtained from the subclass'
0068 Summarize method. (See JObject::Summarize for details). If the data
0069 object inherits from ROOT's TObject then an attempt is made to extract
0070 the data members via the dictionary. Note that this relies on the
0071 dictionary being available in the plugin and there are limitations
0072 to the complexity of the objects that can be displayed.
0073
0074 When the debugger window is opened (by pushing the "Debugger" button
0075 on the main GUI window), it will stall event processing so that single
0076 events can be examined and stepped through. To stall processing on the
0077 very first event, the JANA process should have the jana:debug_mode
0078 config. parameter set to a non-zero value when it is started. e.g.
0079
0080 ```
0081 jana -Pplugins=JTest,janacontrol -Pjana:debug_mode=1
0082 ```
0083
0084 Once an event is loaded, click on a factory to display a list of
0085 objects it created for this event (displayed as the object's hexadecimal
0086 address). Click on an object to display its content summary (if they
0087 are accessible). n.b. clicking on a factory will NOT cause the factory
0088 algorithm to activate and create objects for the event. It will only
0089 display objects created by other plugins having activated the algorithm.