Neels Hofmeyr | c0827c4 | 2017-04-23 15:04:19 +0200 | [diff] [blame] | 1 | [[debugging]] |
| 2 | == Debugging |
| 3 | |
Pau Espin Pedrol | 8ccd99a | 2020-03-16 19:48:02 +0100 | [diff] [blame] | 4 | {app-name} is a complex program which at the same time orchestrates sets of |
| 5 | other complex programs to form a network of nodes. As such, it can be sometimes |
| 6 | challenging to find out what is going on during a trial run. This section aims |
| 7 | at providing some tips on how to debug possible issues. |
| 8 | |
| 9 | === Logging level |
| 10 | |
| 11 | {app-name} runs by default under 'info' log level. As a first debugging step, it |
| 12 | is always a good idea to increase log verbosity. By switching to debug level |
| 13 | (command line argument '-l dbg'), a lot more information and events are displayed which |
| 14 | can give a much better idea to understand possible misconfigurations or wrong |
| 15 | steps. |
| 16 | |
| 17 | In any case, {app-name} usually provides several log files of interest. In |
| 18 | general, both a 'log' and a 'log_brief' are stored directly under the trial's |
| 19 | run directory, the first containing output up to debug level included, while the |
| 20 | second contains output up to info level included. Furthermore, {app-name} writes |
| 21 | a debug level log file per test case under each test's run directory. |
| 22 | |
| 23 | It is also in general useful to enable the '-T' command line argument. By using |
| 24 | it, it will instruct {app-name} to write the full backtrace to the log output |
| 25 | when something wrong happens, such an unexpected exception. |
| 26 | |
| 27 | [[pdb]] |
| 28 | === python debugger |
| 29 | |
| 30 | {app-name} can be further debugged using python's debugger 'pdb'. Easiest way to |
| 31 | use it is to modify the python code were you want to break and add this code: |
| 32 | ---- |
| 33 | import pdb; pdb.set_trace() |
| 34 | ---- |
| 35 | |
| 36 | When {app-name} runs over that code, it will pause and provide a debugging |
| 37 | interactive shell, where one can inspect variables, execute code, etc. |
| 38 | |
| 39 | TIP: Remember {app-name} is managed by its internal main loop, meaning if you |
| 40 | jump into a debugger console you will still need to give back control to the |
| 41 | main loop for events to be processed and checks done. That can be done for |
| 42 | instance by calling the 'MainLoop.sleep(log_obj, secs)' internal API in general |
| 43 | or `sleep(secs)' under test context. |
| 44 | |
| 45 | === debug suite |
| 46 | |
| 47 | Sometimes, however, one may be interested in debugging the behavior of the |
| 48 | software under test by {app-name} rather than {app-name} itself. For instance, |
| 49 | one may simply want to set up a full running network of nodes and keep it up |
| 50 | until some manual tests are done, or one may want {app-name} to do so at a given |
| 51 | point of time. |
| 52 | |
| 53 | To fulfill this kind of scenarios, {app-name} provides some code available for |
| 54 | tests to gain access to a high-level interactive console which is fully |
| 55 | integrated with {app-name}'s own main loop. So the approach here is usually to |
| 56 | write a regular test (with its corresponding <<suite_conf,suite.conf>>) to set |
| 57 | up and run all required processes and then allow it to jump into the interactive |
| 58 | console instance. Then the test pulls received commands from it and it is |
| 59 | responsible for parsing and implementing them. One command can for instance ask |
| 60 | a modem to send an sms to another. Another command can for instance jump into a |
| 61 | <<pdb,debugger console>>. |
| 62 | |
| 63 | The interactive console is available to tests through the 'prompt' method, and |
| 64 | its implementation can be found under 'method input_polling' in 'util.py'. |
| 65 | |
| 66 | An interactive console example as explained in this section can be found under |
| 67 | the 'debug/interactive.py' test in osmo-gsm-tester.git. |