How to use the ska-tango-event-monitor script
=============================================

This guide describes how to get started using SKA Tango Event Monitor.

Installation
------------

To install the ``ska-tango-event-monitor`` script in your virtual environment, run the following:

.. code :: shell

   pip install --require-virtualenv ska-tango-event-monitor --extra-index-url https://artefact.skao.int/repository/pypi-internal/simple

.. warning ::

   ska-tango-event-monitor makes use of additional DServer commands provided by cppTango >=10.1 in order to monitor the event system.  This is a requirement on the device servers being queried and not on the script itself. See https://tango-controls.gitlab.io/cppTango/10.1.1/query_event_system.html for details on these commands.

Usage
-----

The script can be used as follows:

.. code :: shell

   ska-tango-event-monitor [options] <device> [<device>...]

Arguments
*********

- ``device``: The devices or admin devices to poll (at least 1 required).
- ``-h, --help``: Show help and exit
- ``--poll-period``: Period between polls in seconds (default: 10.0).
- ``-o, --output``: File to save data to, one JSON object per line (default: None).
- ``-a, --append``: Append to file (default: False).
- ``-c, --compression``: Force a compression algorithm to use for output file, otherwise it is determined from the file extension.  One of {none,gz,bz2,xz}.
- ``-m, --monitor-perf``: Enable performance monitoring

Example
*******

.. code :: shell

   ska-tango-event-monitor my/running/device my/running/device2 --poll-period 5 -o output.json.xz

This command will monitor the specified Tango devices, polling every 5 seconds, and save the output to `output.json.xz`.