Merge pull request #266 from flask-dashboard/generalized-schedulers

Generalized schedulers

docs/functionality.rst

@@ -251,26 +251,59 @@ You might wish to know how the number of unique users, the size of your
 database, or the total number of endpoints have evolved over time. This is now
 easy to visualize using FMD.
 
-An example of a custom graph is shown below. FMD will execute :code:`my_func()`
-every hour and a half and the graph will appear in the **Custom graphs** menu.
+An example of a custom graph is shown below. FMD will execute :code:`on_the_minute()`
+every minute at the second 01 and the graph will appear in the **Custom graphs** menu.
 
   .. code-block:: python
 
-     def my_func():
-         # here should be something actually useful
-         return 35
+   def on_the_minute():
+       print(f"On the minute: {datetime.datetime.now()}")
+       return int(random() * 100 // 10)
 
-     schedule = {'weeks': 0,
-                  'days': 0,
-                  'hours': 1,
-                  'minutes': 30,
-                  'seconds': 0}
 
-     dashboard.add_graph('Graph1', lambda: my_func(), **schedule)
+   minute_schedule = {'second': 00}
+
+   dashboard.add_graph("On Half Minute", on_the_minute, "cron", **minute_schedule)
+
+
+Note the "cron" argument to the add graph.
+Just like in the case of the unix cron utility you can use
+more complex schedules. For example, if you want to collect
+the data every day at midnight you would use:
+
+  .. code-block:: python
+
+   midnight_schedule = {'month':"*",
+                        'day': "*",
+                        'hour': 23,
+                        'minute': 59,
+                        'second': 00}
+
+Besides cron, there's also the "interval" schedule type, which
+is exemplified in the following snippet:
+
+  .. code-block:: python
+
+   def every_ten_seconds():
+       print(f"every_ten_seconds!!! {datetime.datetime.now()}")
+       return int(random() * 100 // 10)
+
+
+   every_ten_seconds_schedule = {'seconds': 10}
+
+   dashboard.add_graph("Every 10 Seconds", every_ten_seconds, "interval", **every_ten_seconds_schedule)
+
 
 
 Note that not all fields in the :code:`schedule` dictionary
-are required, only the non-zero ones.
+are required, only the non-zero / non-star ones.
+
+Also, note that in the "cron" graph types you use singular names (e.g. second)
+while in the "interval" you use plurals (e.g. seconds).
+
+Finally, the implementation of the scheduler in the FMD
+is based on the appscheduler.schedulers.Background schedulers
+about which you can read more `in the corresponding documentation page <apscheduler.schedulers>`_.
 
 Need more information?
 ----------------------

flask_monitoringdashboard/__init__.py

@@ -77,14 +77,16 @@ def bind(app, schedule=True):
     atexit.register(flush_cache)
 
 
-def add_graph(title, func, **schedule):
+def add_graph(title, func, trigger="interval", **schedule):
     """
     Add a custom graph to the dashboard. You must specify the following arguments
     :param title: title of the graph (must be unique)
     :param schedule: dict containing values for weeks, days, hours, minutes, seconds
     :param func: function reference without arguments
+    :param trigger: str|apscheduler.triggers.base.BaseTrigger trigger: trigger that determines when
+            ``func`` is called
     """
     from flask_monitoringdashboard.core import custom_graph
 
     graph_id = custom_graph.register_graph(title)
-    custom_graph.add_background_job(func, graph_id, **schedule)
+    custom_graph.add_background_job(func, graph_id, trigger, **schedule)

flask_monitoringdashboard/core/custom_graph/__init__.py

@@ -29,13 +29,13 @@ def register_graph(name):
         return get_graph_id_from_name(db_session, name)
 
 
-def add_background_job(func, graph_id, **schedule):
+def add_background_job(func, graph_id, trigger, **schedule):
     def add_data():
         with session_scope() as db_session:
             add_value(db_session, graph_id, func())
 
     add_data()  # already call once, so it can be verified that the function works
-    scheduler.add_job(func=add_data, trigger="interval", **schedule)
+    scheduler.add_job(func=add_data, trigger=trigger, **schedule)
 
 
 def get_custom_graphs():

flask_monitoringdashboard/main.py

@@ -7,22 +7,44 @@
     Note: This is not used when the flask_monitoring_dashboard
     is attached to your flask application.
 """
-import random
+from random import random
+import datetime
 import time
 
 from flask import Flask
 
-
 import flask_monitoringdashboard as dashboard
 
 app = Flask(__name__)
 
 dashboard.config.version = '3.2'
 dashboard.config.group_by = '2'
 dashboard.config.database_name = 'sqlite:///data.db'
+
+
 # dashboard.config.database_name = 'mysql+pymysql://user:password@localhost:3306/db1'
 # dashboard.config.database_name = 'postgresql://user:password@localhost:5432/mydb'
 
+
+def on_the_minute():
+    print(f"On the minute: {datetime.datetime.now()}")
+    return int(random() * 100 // 10)
+
+
+minute_schedule = {'second': 00}
+
+dashboard.add_graph("On Half Minute", on_the_minute, "cron", **minute_schedule)
+
+
+def every_ten_seconds():
+    print(f"every_ten_seconds!!! {datetime.datetime.now()}")
+    return int(random() * 100 // 10)
+
+
+every_ten_seconds_schedule = {'seconds': 10}
+
+dashboard.add_graph("Every 10 Seconds", every_ten_seconds, "interval", **every_ten_seconds_schedule)
+
 dashboard.bind(app)