Add an indication listener to pywbemtools

[KSchopmeyer]

Goal: A command line mechanism that can listen for indications and account for them in multiple ways.

Basic requirements:

1. Ability to start and stop a particular listener in the command line environment. Should be able to support multiple listeners on different ports simultaneously in the client cmd line environment
2. Ability to see the status of a listener (indications received, etc.)
3. (Optional) - Ability to filter received indications into different catagories for display, etc.

Some alternatives:

1. New tool that is a standalone listener.
   a. Each listener started from the command line would have one listen port and defintion of disposition of results. The listener would operate in the started process so that any use of multiple listeners would depend on the shell to start listeners in the background. Normally termination would be simplistic through something like Ctro-C.
   b. A multi-port listener app that would allow the creation of multiple listeners in a single app with the actual listeners in the background. The app would communicate requests for start, stop, status for each active listener.
   c. Add a listener group to pywbemcli that would allow control of multiple listeners in the background. Questions here include whether pywbemcli would have to be active during the life of the listeners or would they be independent processes?

Each listener should have the following basic controls:

1. Start and stop

2. Options for the destination of indications (display, log, count, pass to somewhere)

3. request status of one or more listeners to get information like (status, count, view indications received, etc.)

4. Command Group in pywbemcli that controls multiple listeners. A listener

[andy-maier]

DISCUSSION: Target release?

[KSchopmeyer]

We agree post 0.8.0

[andy-maier]

My vote would be that each started listener is a pywbemcli command that runs as a separate process, without having a managing pywbemcli command around. The "psutil" package can be used to deal with the processes. It supports all of our platforms and Python releases.

If we run the listeners as separate processes without having a managing pywbemcli command around, then it should also be supported for a user to start the pywbemcli listener manually, i.e. without using a managing pywbemcli command.

Listing the listeners can be done by looking at the Python processes that have a command line matching a running pywbemcli listener. At the OS level, processes have a name. In case of the pywbemcli Python script, "Python" is the process name. The command line parameters of the Python process would need to be examined to find those that are pywbemcli invocations, and that could also be used to identify those pywbemcli invocations that are running listeners (as opposed to currently running other commands or interactive sessions). The psutil package supports access to the process command line, as a list of command line arguments, e.g. when having an interactive session of pywbemcli open:

>>> import psutil
>>> from pprint import pprint
>>> pprint([p.cmdline() for p in psutil.process_iter() if p.name() == 'Python' and len(p.cmdline()) > 1 and 'pywbemcli' in p.cmdline()[1]])
[['/usr/local/Cellar/[email protected]/3.8.7_2/Frameworks/Python.framework/Versions/3.8/Resources/Python.app/Contents/MacOS/Python',
  '/Users/maiera/virtualenvs/pywbemtools38/bin/pywbemcli',
  '-o',
  'txt']]

The algorithm used above would need to be refined, because Python command line options, if specified, also show up in the command line. Basically it requires iterating the items of the python process' command line to find the pywbemcli command, if any, and then parsing that along with the remaining arguments after it as the pywbemcli command line. That would support all cases how pywbemcli can be started as a command, except for using the python command with its -c cmd or -m module option or with its - command and piping the pywbemcli script into its stdin. I think these exceptions would all be rather exotic ways to run the pywbemcli command and I would have no heartburn to not support them.

I think each started listener should have a name that is used to control it. That is not the process name at the OS level, but would be something that is visible when listing the processes. One place for storing the name that comes to mind (at least if we want to allow users to manually run listeners) is the command line itself. Alternatively, the pywbemcli command that actually runs the listener could register its name somewhere, e.g. in a file in the home directory.

I think we need a capability to further filter the indications received by a listener, i.e. on top of the CIM filter that is part of the CIM subscription.

One discussion point is whether this should be a new command group in the "pywbemcli" command, vs a new command. I vote for a new command group in the existing "pywbemcli" command. We already have some precedence where for example, the general options for specifying a target WBEM server are not used, e.g. in most commands of the "connection" command group.

Proposal for the commands:

• pywbemcli listener start --name NAME {run-options} - start a listener under the name NAME using the specified run options (basically starts a "listener run" command as a detached child process)
• pywbemcli listener stop NAME - stop the running listener named NAME. That causes that listener to no longer exist.
• pywbemcli listener run --name NAME {run-options} - run as a listener under the name NAME using the specified run options. Can be stopped with break signal (e.g. from keyboard interrupt or killing the process).
• pywbemcli listener list - list the running listeners
• pywbemcli listener show NAME - show the properties of the running listener named NAME

Properties of a running listener:

• name
• count
• filters
• destination

Note that in this proposal, a listener would not know its potential WBEM servers sending indications, i.e. it would not know any subscriptions or server-side filters. Also, a listener would not have a status, since only running listeners exist.

run-options:

• Options to set the protocol and port it listens on.
• Options to set a destination, e.g. add to the log, invoke a command, call a Python function. Maybe the general options can be used to some extent, e.g. for specifying the output format or for specifying where the log goes. For invoking commands, JSON would be a good format, but that probably requires support for JSON output of CIM instances in pywbem. Just counting could be achieved by not setting a destination.
• Options to filter indications (by inclusion and exclusion?).

We also need something to manage subscriptions. Since a single listener can be the destination of multiple subscriptions from multiple WBEM servers, and since WBEM servers may control their subscriptions by other administrative actions than through the subscription part of the Indications profile, this would probably be a separate pywbemcli command group.

[andy-maier]

PR #971 (merged) adds the pywbemlistener command.

Since there are separate issues for docs and test, this issue is considered done:

• Tests: issue Tests for pywbemlistener command #981
• Docs: issue Finish the documentation of pywbemlistener #980