Auto-upsert Sentry cron monitors for the tasks (#42)

Sentry introduced an ability to automatically create cron monitors in
case the monitor config is provided along with the payload:
https://docs.sentry.io/platforms/python/crons/#configuring-cron-monitors

In case we are positive that Sentry is used within the project, instead
of simply sending the signal, we can upsert the config right away to
reduce the amount of manual work.


Co-authored-by: Johannes Maron <johannes@maron.family>

Author: amureki

README.md

@@ -104,9 +104,12 @@ def my_interval_task():
 
 ### Sentry Cron Monitors
 
-If you use [Sentry] you can add cron monitors to your tasks.
+If you use [Sentry] suitable tasks will be automatically monitored.
 The monitor's slug will be the actor's name. Like `my_task` in the example above.
 
+Certain triggers are not supported by Sentry as well as sub-minute intervals.
+In these cases, no monitor will be created and no telemetry will be sent.
+
 ### The crontask command
 
 ```ShellSession

crontask/__init__.py

@@ -13,12 +13,13 @@
 from django.utils import timezone
 
 from . import _version
+from .contrib import sentry
+
+__all__ = ["cron", "interval", "scheduler", "VERSION", "__version__"]
 
 __version__ = _version.version
 VERSION = _version.version_tuple
 
-__all__ = ["cron", "interval", "scheduler"]
-
 
 class LazyBlockingScheduler(BlockingScheduler):
     """Avoid annoying info logs for pending jobs."""
@@ -45,21 +46,15 @@ def cron(schedule: str | BaseTrigger) -> typing.Callable[[Task], Task]:
         def cron_test():
             print("Cron test")
 
-
-    Please don't forget to set up a sentry monitor for the actor, otherwise you won't
-    get any notifications if the cron job fails.
-
-    The monitor slug is your actor name, the schedule should be set to the same
-    cron schedule as the cron decorator. The schedule type should be set to cron.
-    The monitors timezone should be set to Europe/Berlin.
+    Sentry cron monitors are automatically upserted on every check-in
+    using the task name as the monitor slug.
     """
 
     def decorator(task: Task) -> Task:
-        trigger = schedule
         if isinstance(schedule, str):
             *_, day_schedule = schedule.split(" ")
-            # CronTrigger uses Python's timezone dependent first weekday,
-            # so in Berlin monday is 0 and sunday is 6. We use literals to avoid
+            # CronTrigger uses Python's timezone-dependent first weekday,
+            # so in Berlin Monday is 0, and Sunday is 6. We use literals to avoid
             # confusion. Literals are also more readable and crontab conform.
             if any(i.isdigit() for i in day_schedule):
                 raise ValueError(
@@ -69,22 +64,10 @@ def decorator(task: Task) -> Task:
                 schedule,
                 timezone=timezone.get_default_timezone(),
             )
-
-        try:
-            from sentry_sdk.crons import monitor
-        except ImportError:
-            fn = task.func
         else:
-            fn = monitor(task.name)(task.func)
-
-        task = type(task)(
-            priority=task.priority,
-            func=fn,
-            queue_name=task.queue_name,
-            backend=task.backend,
-            takes_context=task.takes_context,
-            run_after=task.run_after,
-        )
+            trigger = schedule
+
+        task = sentry.monitor_cron_task(task, trigger)
 
         scheduler.add_job(
             func=task.enqueue,

crontask/contrib/__init__.py

@@ -0,0 +1,88 @@
+import typing
+
+from apscheduler.triggers.base import BaseTrigger
+from apscheduler.triggers.calendarinterval import CalendarIntervalTrigger
+from apscheduler.triggers.cron import CronTrigger
+from apscheduler.triggers.interval import IntervalTrigger
+from django.tasks import Task
+from django.utils import timezone
+
+
+def trigger_to_monitor_config(trigger: BaseTrigger) -> dict[str, typing.Any] | None:
+    """Convert an APScheduler trigger to a Sentry monitor configuration if possible."""
+    tz = str(timezone.get_default_timezone())
+    match trigger:
+        case CronTrigger():
+            fields = {f.name: str(f) for f in trigger.fields}
+            return {
+                "schedule": {
+                    "type": "crontab",
+                    "value": "{minute} {hour} {day} {month} {day_of_week}".format(
+                        **fields
+                    ),
+                },
+                "timezone": tz,
+            }
+        case IntervalTrigger():
+            seconds = trigger.interval.total_seconds()
+            for unit, size in (
+                ("year", 31536000),
+                ("month", 2592000),
+                ("week", 604800),
+                ("day", 86400),
+                ("hour", 3600),
+                ("minute", 60),
+            ):
+                if seconds % size == 0:
+                    return {
+                        "schedule": {
+                            "type": "interval",
+                            "value": seconds // size,
+                            "unit": unit,
+                        },
+                        "timezone": tz,
+                    }
+            return None  # Less than a minute
+        case CalendarIntervalTrigger():
+            fields = {
+                "year": trigger.years,
+                "month": trigger.months,
+                "week": trigger.weeks,
+                "day": trigger.days,
+            }
+            set_fields = {k: v for k, v in fields.items() if v}
+            if len(set_fields) == 1:
+                ((unit, value),) = set_fields.items()
+                return {
+                    "schedule": {"type": "interval", "value": value, "unit": unit},
+                    "timezone": tz,
+                }
+            return None
+        case _:
+            return None
+
+
+def monitor_cron_task(task: Task, trigger: BaseTrigger) -> Task:
+    """
+    Wrap the task function in a Sentry monitor for a suitable trigger.
+
+    You don't need to create the monitor in advance since
+    the Sentry monitor configuration is upserted on each task execution.
+    If the trigger is not supported, the task is returned unchanged.
+    """
+    try:
+        from sentry_sdk import monitor
+    except ImportError:
+        return task
+    else:
+        if monitor_config := trigger_to_monitor_config(trigger):
+            return type(task)(
+                priority=task.priority,
+                func=monitor(task.name, monitor_config=monitor_config)(task.func),
+                queue_name=task.queue_name,
+                backend=task.backend,
+                takes_context=task.takes_context,
+                run_after=task.run_after,
+            )
+
+    return task

crontask/contrib/sentry.py

@@ -0,0 +1,93 @@
+import datetime
+
+import pytest
+from apscheduler.triggers.calendarinterval import CalendarIntervalTrigger
+from apscheduler.triggers.cron import CronTrigger
+from apscheduler.triggers.date import DateTrigger
+from apscheduler.triggers.interval import IntervalTrigger
+from crontask.contrib.sentry import trigger_to_monitor_config
+from django.utils import timezone
+
+
+def test_monitor_config__cron_trigger():
+    assert trigger_to_monitor_config(
+        CronTrigger.from_crontab("0 2 * * *", timezone=timezone.get_default_timezone())
+    ) == {
+        "schedule": {"type": "crontab", "value": "0 2 * * *"},
+        "timezone": "Europe/Berlin",
+    }
+
+
+def test_monitor_config__cron_trigger__with_day_of_week():
+    # Literals are allowed, first day of the week is Sunday:
+    # https://discord.com/channels/621778831602221064/1496192154702315560
+    trigger = CronTrigger.from_crontab(
+        "0 2 * * Mon-Fri", timezone=timezone.get_default_timezone()
+    )
+    assert trigger_to_monitor_config(trigger) == {
+        "schedule": {"type": "crontab", "value": "0 2 * * mon-fri"},
+        "timezone": "Europe/Berlin",
+    }
+
+
+@pytest.mark.parametrize(
+    "seconds,expected",
+    [
+        (60, {"type": "interval", "value": 1, "unit": "minute"}),
+        (300, {"type": "interval", "value": 5, "unit": "minute"}),
+        (3600, {"type": "interval", "value": 1, "unit": "hour"}),
+        (86400, {"type": "interval", "value": 1, "unit": "day"}),
+        (86400 * 3, {"type": "interval", "value": 3, "unit": "day"}),
+        (604800, {"type": "interval", "value": 1, "unit": "week"}),
+        (2592000, {"type": "interval", "value": 1, "unit": "month"}),
+        (31536000, {"type": "interval", "value": 1, "unit": "year"}),
+        (13 * 2592000, {"type": "interval", "value": 13, "unit": "month"}),
+        (12 * 604800, {"type": "interval", "value": 12, "unit": "week"}),
+    ],
+)
+def test_monitor_config__interval_trigger(seconds, expected):
+    trigger = IntervalTrigger(seconds=seconds, timezone=timezone.get_default_timezone())
+    assert trigger_to_monitor_config(trigger) is not None
+    assert trigger_to_monitor_config(trigger)["schedule"] == expected
+
+
+@pytest.mark.parametrize(
+    "seconds",
+    [
+        42,  # less than 60 seconds
+        69,  # not a multiple of any supported unit
+    ],
+)
+def test_monitor_config__unsupported_interval_trigger(seconds):
+    trigger = IntervalTrigger(seconds=seconds, timezone=timezone.get_default_timezone())
+    assert trigger_to_monitor_config(trigger) is None
+
+
+@pytest.mark.parametrize(
+    "kwargs,expected",
+    [
+        ({"years": 1}, {"type": "interval", "value": 1, "unit": "year"}),
+        ({"months": 2}, {"type": "interval", "value": 2, "unit": "month"}),
+        ({"weeks": 1}, {"type": "interval", "value": 1, "unit": "week"}),
+        ({"days": 7}, {"type": "interval", "value": 7, "unit": "day"}),
+    ],
+)
+def test_monitor_config__calendar_interval_trigger(kwargs, expected):
+    trigger = CalendarIntervalTrigger(
+        **kwargs, timezone=timezone.get_default_timezone()
+    )
+    assert trigger_to_monitor_config(trigger)["schedule"] == expected
+
+
+@pytest.mark.parametrize(
+    "trigger",
+    [
+        IntervalTrigger(seconds=30, timezone=timezone.get_default_timezone()),
+        CalendarIntervalTrigger(
+            months=1, days=1, timezone=timezone.get_default_timezone()
+        ),
+        DateTrigger(run_date=datetime.datetime(2021, 1, 1)),
+    ],
+)
+def test_monitor_config__unsupported(trigger):
+    assert trigger_to_monitor_config(trigger) is None