Refactor FileWatchSensor to remove logshipper

.gitignore

@@ -33,6 +33,9 @@ conf/st2.travis.conf
 # generated GitHub Actions conf
 conf/st2.githubactions.conf
 
+# Vagrant
+.vagrant/
+
 # Installer logs
 pip-log.txt
 

CHANGELOG.rst

@@ -13,6 +13,15 @@ Changed
 ~~~~~~~
 * Bumped `jsonschema` 2.6.0 -> 3.2.0 now that python3.6 is not supported. #6118
 
+* The FileWatchSensor in the linux pack uses `watchdog` now instead of `logshipper` (`logshipper` and its requirement `pyinotify` are unmaintained).
+  The `watchdog` project is actively maintained, and has wide support for Linux, MacOS, BSD, Windows, and a polling fallback implementation.
+  Dropping `pyinotify` has a side benefit of allowing MacOS users to more easily hack on StackStorm's code, since `pyinotify` cannot install on MacOS.
+
+  The FileWatchSensor is now an excellent example of how to write a sensor following this refactor. It breaks up the code into well structured classes
+  that all have a single focus. You can also run the sensor Python script itself, which makes development and testing much easier. #5096
+
+  Contributed by @blag
+
 Added
 ~~~~~
 * Continue introducing `pants <https://www.pantsbuild.org/docs>`_ to improve DX (Developer Experience)

contrib/linux/README.md

@@ -2,32 +2,42 @@
 
 This pack contains actions for commonly used Linux commands and tools.
 
-## Configuration
+## Sensors
+
+### FileWatchSensor
+
+This sensor monitors files specified in rules (under trigger parameters) for new lines.
+Once a new line is detected, a trigger instance is emitted.
+
+#### Adding a file path to the file watch sensor
 
-* ``file_watch_sensor.file_paths`` - A list of paths to the files to monitor.
-  Note: Those need to be full paths to the files (e.g. ``/var/log/auth.log``)
-  and not directories (files don't need to exist yet when the sensor is ran
-  though).
+To tell the FileWatchSensor to start watching a new file, define a rule that
+- uses the `linux.file_watch.line` trigger type
+- pass the `file_path` to watch under trigger parameters.
 
-Example:
+For example, this rule would cause the sensor to start watching `/tmp/st2_test`:
 
 ```yaml
 ---
-file_watch_sensor:
-  file_paths:
-    - /opt/data/absolute_path_to_file.log
-```
+name: sample_rule_file_watch
+description: Run echo on changes to /tmp/st2_test
+enabled: false
 
-## Sensors
+trigger:
+  type: linux.file_watch.line
+  parameters:
+    file_path: /tmp/st2_test
 
-### FileWatchSensor
+action:
+  ref: core.local
+  parameters:
+    cmd: echo "{{trigger}}"
+```
 
-This sensor monitors specified files for new new lines. Once a new line is
-detected, a trigger is emitted.
 
-### linux.file_watch.line trigger
+#### linux.file_watch.line trigger
 
-Example trigger payload:
+Example trigger instance payload:
 
 ```json
 {

contrib/linux/requirements.txt

@@ -1,3 +1 @@
-# used by file watcher sensor
-pyinotify>=0.9.5,<=0.10 ; platform_system=="Linux"
-logshipper@ git+https://github.com/StackStorm/logshipper.git@stackstorm_patched ; platform_system=="Linux"
+watchdog

contrib/linux/sensors/README.md

@@ -1,6 +1,6 @@
 ## NOTICE
 
-File watch sensor has been updated to use trigger with parameters supplied via a rule approach. Tailing a file path supplied via a config file is now deprecated.
+File watch sensor has been updated to use trigger with parameters supplied via a rule approach.
 
 An example rule to supply a file path is as follows: