Improve run_async documentation and examples

[lcfd]

We are trying to get logs data about an event when it occurs directly in Python. Because we are using

runner_async_thread, runner_object = ansible_runner.interface.run_async(...

There appears to be no clear way in the documentation to see the output of playbook tasks as they run.

The documentation for the run_async() helper function says:

The Runner object can be inspected during execution.

… but does not elaborate or provide any clues regarding precisely how that inspection can be performed or what information can be inspected.

I started looking at event_callback but as far as I can understand it's not really usable outside of Runner's context.

The only plausible way to get those data that I found is to create a custom plugin similar to ansible-runner-http. Is that the only way?

There is also an old open question on StackOverflow that talks about this need.

[Shrews]

Yeah, admittedly, the docs are not great here.

You can repeatedly query the runner_object.events attribute to get any event data that has been returned so far. But you'll have to keep re-reading it until the process finishes in order to get all of the data. And any data read in previous accesses to events will be repeated each time since that attribute basically just reads all of the event files in the proper artifacts directory. The rc attribute of the Runner object will change from None to some other value when the process finishes. So, something VERY hacky:

while runner_object.rc is None:
    for event in runner_object.events:
        print(f"Got event: {event}")

... and then one final read of events after that to get any remaining. Each time through that while would read ALL events thus far, so you'd see duplicates, as I mentioned above.

Parsing and coalescing the event data is something you'll have to do yourself. We do insert unique UUIDs (uuid key) and counters (counter key) into the JSON data that can help you identify and sort events.

[Shrews]

I've updated this ticket to turn it into a documentation bug for us to improve that area.

[lcfd]

Thank you @Shrews for the answer and for opening the doc improvement issue.

So, something VERY hacky:

Yes, I've seen this solution in another answer somewhere. It didn't seem very reliable.

so you'd see duplicates

Useful advice, we will pay attention 👍🏼

---

If I may give feedback, the presentation of the documentation can be improved a bit. The general sensation of reading a "wall of text" is strong and doesn't help comprehension. This is why I particularly appreciate this intention to improve the documentation 🚀

[eqrx]

If you would be so kind you could raise a PR that adds your finding :) Would appreciate it!

[Akasurde]

@lcfd Would you be interested in raising a PR with your findings?