perun.monitoring.monitor
========================

.. py:module:: perun.monitoring.monitor

.. autoapi-nested-parse::

   Monitor module.



Attributes
----------

.. autoapisummary::

   perun.monitoring.monitor.log


Classes
-------

.. autoapisummary::

   perun.monitoring.monitor.MonitorStatus
   perun.monitoring.monitor.PerunMonitor


Module Contents
---------------

.. py:data:: log

.. py:class:: MonitorStatus(*args, **kwds)

   Bases: :py:obj:`enum.Enum`


   Represents the status of a monitor.

   Attributes
   ----------
       SETUP: The monitor is being set up.
       RUNNING: The monitor is running.
       PROCESSING: The monitor is processing data.
       SCRIPT_ERROR: An error occurred in the monitor's script.
       PERUN_ERROR: An error occurred in the Perun system.
       MPI_ERROR: An error occurred in the MPI system.
       FILE_NOT_FOUND: The required file was not found.
       SUCCESS: The monitor completed successfully.


   .. py:attribute:: SETUP


   .. py:attribute:: RUNNING


   .. py:attribute:: PROCESSING


   .. py:attribute:: SCRIPT_ERROR


   .. py:attribute:: PERUN_ERROR


   .. py:attribute:: MPI_ERROR


   .. py:attribute:: FILE_NOT_FOUND


   .. py:attribute:: SUCCESS


.. py:class:: PerunMonitor(app: perun.monitoring.application.Application, comm: perun.comm.Comm, backends: Dict[str, perun.backend.backend.Backend], l_assigned_sensors: Dict[str, Tuple], config: configparser.ConfigParser)

   The PerunMonitor class is responsible for monitoring the application and collecting data.

   Parameters
   ----------
   app : Application
       The application to be monitored.
   comm : Comm
       The communication object for inter-process communication.
   l_sensors_config : Dict[str, Set[str]]
       The configuration for local sensors.
   backends : Dict[str, Backend]
       The backends for data collection.
   config : ConfigParser
       The configuration parser object.

   Attributes
   ----------
   _app : Application
       The application to be monitored.
   _comm : Comm
       The communication object for inter-process communication.
   _l_sensors_config : Dict[str, Tuple]
       The configuration for local sensors.
   _backends : Dict[str, Backend]
       The backends for data collection.
   _config : ConfigParser
       The configuration parser object.
   status : MonitorStatus
       The current status of the monitor.


   .. py:attribute:: _app


   .. py:attribute:: _comm


   .. py:attribute:: _backends


   .. py:attribute:: _l_assigned_sensors


   .. py:attribute:: _config


   .. py:attribute:: status


   .. py:method:: _reset_subprocess_handlers() -> None

      Reset subprocess handlers.



   .. py:method:: run_application(run_id: str, record: bool = True) -> Tuple[MonitorStatus, Optional[perun.data_model.data.DataNode], Any]

      Run the application and returns the monitor status and data node.

      Parameters
      ----------
      run_id : str
          The ID of the run.
      record : bool, optional
          Whether to record data or not. Defaults to True.

      Returns
      -------
      Tuple[MonitorStatus, Optional[DataNode], Any]
          A tuple containing the monitor status and the data node, and the application result.

      Raises
      ------
      SystemExit
          If the application exits using exit(), quit(), or sys.exit().
      Exception
          If an error occurs in the monitored script.

      Notes
      -----
      - If `record` is True, the method performs the following steps:
          1. Gets the sensor configuration.
          2. If there are assigned devices, creates a subprocess to run the application.
          3. Starts the application and waits for it to be ready.
          4. Runs the application.
          5. Stops the application and retrieves the data.
      - If `record` is False, the method simply runs the application without recording data.




   .. py:method:: _run_python_app(run_id: str) -> Tuple[MonitorStatus, Optional[perun.data_model.data.DataNode], Any]


   .. py:method:: _run_binary_app(run_id: str) -> Tuple[MonitorStatus, Optional[perun.data_model.data.DataNode], Any]


   .. py:method:: _handle_failed_run() -> Optional[perun.data_model.data.DataNode]


   .. py:method:: _process_single_run(run_id: str, starttime_ns: int, available_ranks: Optional[List[int]] = None) -> Optional[perun.data_model.data.DataNode]

      Collect data from subprocess and pack it in a data node.

      Parameters
      ----------
      run_id : str
          The id to use for the data node.
      starttime_ns : int
          Start time of the run.

      Returns
      -------
      Optional[DataNode]
          If the rank spawned a subprocess, returns the data node with the data.