diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4b0cb0427..086bd57889 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -281,7 +281,7 @@ For feature work, take a look at the current [Enhancements](https://github.com/a If it has someone assigned to it then that person is the person responsible for working the enhancement. If you feel like you could contribute then reach out to that person. -Fixing bugs, adding translations, and updating the documentation are always appreciated, so reviewing the backlog of issues is always a good place to start. +Fixing bugs, adding translations, and updating the documentation are always appreciated, so reviewing the backlog of issues is always a good place to start. For extra information on debugging tools, see [Debugging](https://github.com/ansible/awx/blob/devel/docs/debugging.md). **NOTE** diff --git a/docs/debugging.md b/docs/debugging.md new file mode 100644 index 0000000000..ee0405af3b --- /dev/null +++ b/docs/debugging.md @@ -0,0 +1,50 @@ +Debugging +========= + + + +Remote Debugging +---------------- +Python processes in Tower's development environment are kept running in the +background via supervisord. As such, interacting with them via Python's +standard `pdb.set_trace()` isn't possible. + +Bundled in our container environment is a remote debugging tool, `rdb`. You +can use it to set remote breakpoints in Tower code and debug interactively over +a telnet session: + +```python + # awx/main/tasks.py + + class SomeTask(awx.main.tasks.BaseTask): + + def run(self, pk, **kwargs): + # This will set a breakpoint and open an interactive Python + # debugger exposed on a random port between 6899-6999. The chosen + # port will be reported as a warning in the Tower logs, e.g., + # + # [2017-01-30 22:26:04,366: WARNING/Worker-11] Remote Debugger:6900: Please telnet into 0.0.0.0 6900. + # + # You can access it from your host machine using telnet: + # + # $ telnet localhost + import rdb + rdb.set_trace() +``` + +Keep in mind that when you interactively debug in this way, any process +that encounters a breakpoint will wait until an active client is established +(it won't handle additional tasks) and concludes the debugging session with +a `continue` command. + +To simplify remote debugging session management, Tower's development +environment comes with tooling that can automatically discover open +remote debugging sessions and automatically connect to them. From your *host* +machine (i.e., _outside_ of the development container), you can run: + +``` +make rdb +``` + +This will open a Python process that listens for new debugger sessions and +automatically connects to them for you. \ No newline at end of file