utFileMonitor Manual

1. Introduction

The utFileMonitor class is a Python utility designed to monitor log files and execute a callback function whenever new lines are added to the file. This is particularly useful in scenarios where you need to react to events logged in a file in real-time.

2. Dependencies

Before using utFileMonitor, ensure you have the following dependencies installed:

• framework.core.logModule
• framework.core.commandModules.consoleInterface
• interactiveShell

3. Class Initialization

To use the utFileMonitor class, you first need to create an instance of it. The constructor takes the following arguments:

• session (consoleInterface): An instance of the consoleInterface class, providing an interface to interact with a console or shell.
• callbackFile (str): The path to the log file you want to monitor.
• callbackFunction (optional): A function to be called when new lines are added to the log file. The function should accept a single string argument, which will contain the new lines.
• prompt (optional, default=":"): The prompt string used to identify the end of a command output in the console.
• log (optional, default=None): An instance of the logModule class for logging purposes. If None, a new logModule instance will be created.

Example:

shell = InteractiveShell()
result = shell.open()
file_monitor = utFileMonitor(shell, "/path/to/logfile.txt", my_callback_function)

4. Callback Function

The callback function you provide will be invoked whenever new lines are appended to the monitored log file. This function should handle the processing of the new log data.

Example Callback Function:

def my_callback_function(new_lines):
  """
  Processes new lines from the log file.

  Args:
    new_lines (str): The new lines added to the log file.
  """
  # Process the new_lines string
  print(f"New lines detected: {new_lines}")

5. Starting the Monitor

Once you have created an instance of utFileMonitor, you can start the monitoring process by calling the start() method. This will spawn a new thread that continuously monitors the log file for changes.

Example:

file_monitor.start()

6. Stopping the Monitor

To stop the monitoring process, you can call the stop() method. This will signal the monitoring thread to exit gracefully.

Example:

file_monitor.stop()

7. Waiting for the Monitor

If you need to wait for the monitoring thread to finish before proceeding, you can use the join() method. This will block the calling thread until the monitoring thread has completed.

Example:

file_monitor.join()

8. Example Usage

The provided code includes an example usage scenario in the if __name__ == '__main__': block. This demonstrates how to create an instance of utFileMonitor, start the monitoring process, and stop it after a certain time.

9. Additional Notes

• The utFileMonitor class uses the stat and tail commands to monitor the log file. Ensure these commands are available in the console environment.
• The monitoring thread checks for new lines every 0.1 seconds. You can adjust this interval by modifying the time.sleep(0.1) call in the monitorFile method.
• The class also includes a basic logging mechanism using the logModule class. You can configure the logging level and output destination as needed.

This user manual provides a basic overview of the utFileMonitor class and its usage. For more detailed information, refer to the code documentation and comments.