feat(quartz): Send monitor config from the trigger with check-ins

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Features
 
+- Quartz `SentryJobListener` now sends a monitor config derived from the trigger with check-ins by default, so Sentry can create or update the monitor from code. Existing monitors take their schedule and time zone from the trigger; set the `sentry-upsert-monitor-config` job or trigger data key to `"false"` to keep managing them in Sentry ([#6216](https://github.com/getsentry/sentry-java/pull/6216))
 - Send a monitor config derived from Spring `@Scheduled` with `@SentryCheckIn` check-ins by default, so Sentry creates or updates the monitor from code. Set `@SentryCheckIn(upsertMonitorConfig = false)` to turn this off ([#6215](https://github.com/getsentry/sentry-java/pull/6215))
 - Report the cellular network technology generation in `device.connection_effective_type`, for example `4g` or `5g` ([#6146](https://github.com/getsentry/sentry-java/pull/6146))
 

sentry-quartz/api/sentry-quartz.api

@@ -7,6 +7,7 @@ public final class io/sentry/quartz/SentryJobListener : org/quartz/JobListener {
 	public static final field SENTRY_CHECK_IN_ID_KEY Ljava/lang/String;
 	public static final field SENTRY_SCOPE_LIFECYCLE_TOKEN_KEY Ljava/lang/String;
 	public static final field SENTRY_SLUG_KEY Ljava/lang/String;
+	public static final field SENTRY_UPSERT_MONITOR_CONFIG_KEY Ljava/lang/String;
 	public fun <init> ()V
 	public fun <init> (Lio/sentry/IScopes;)V
 	public fun getName ()Ljava/lang/String;

sentry-quartz/build.gradle.kts

@@ -34,6 +34,8 @@ dependencies {
   testImplementation(libs.kotlin.test.junit)
   testImplementation(libs.mockito.kotlin)
   testImplementation(libs.mockito.inline)
+  testImplementation(libs.google.truth)
+  testImplementation(libs.quartz)
 }
 
 tasks.withType<JavaCompile>().configureEach {

sentry-quartz/src/main/java/io/sentry/quartz/SentryJobListener.java

@@ -5,20 +5,33 @@
 import io.sentry.CheckInStatus;
 import io.sentry.IScopes;
 import io.sentry.ISentryLifecycleToken;
+import io.sentry.MonitorConfig;
 import io.sentry.ScopesAdapter;
 import io.sentry.SentryIntegrationPackageStorage;
 import io.sentry.SentryLevel;
 import io.sentry.protocol.SentryId;
 import io.sentry.util.LifecycleHelper;
+import io.sentry.util.MonitorConfigUtils;
 import io.sentry.util.Objects;
 import io.sentry.util.TracingUtils;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Locale;
+import java.util.TimeZone;
+import java.util.regex.Pattern;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
+import org.quartz.CronTrigger;
 import org.quartz.JobDataMap;
+import org.quartz.JobDetail;
 import org.quartz.JobExecutionContext;
 import org.quartz.JobExecutionException;
 import org.quartz.JobListener;
+import org.quartz.Scheduler;
+import org.quartz.SchedulerException;
+import org.quartz.SimpleTrigger;
+import org.quartz.Trigger;
 
 @ApiStatus.Experimental
 public final class SentryJobListener implements JobListener {
@@ -32,6 +45,19 @@ public final class SentryJobListener implements JobListener {
   public static final String SENTRY_SLUG_KEY = "sentry-slug";
   public static final String SENTRY_SCOPE_LIFECYCLE_TOKEN_KEY = "sentry-scope-lifecycle";
 
+  /**
+   * Job or trigger data key. The listener sends a monitor config from the trigger with check-ins by
+   * default; set this to {@code "false"} to manage the monitor's schedule in Sentry instead.
+   */
+  public static final String SENTRY_UPSERT_MONITOR_CONFIG_KEY = "sentry-upsert-monitor-config";
+
+  private static final @NotNull List<String> DAY_NAMES =
+      Arrays.asList("SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT");
+
+  // Quartz ignores a step after a name, so SUN/2 is every Sunday
+  private static final @NotNull Pattern NAME_STEP =
+      Pattern.compile("(^|,)[A-Za-z]{3}(-[A-Za-z]{3})?/");
+
   private final @NotNull IScopes scopes;
 
   public SentryJobListener() {
@@ -55,15 +81,18 @@ public void jobToBeExecuted(final @NotNull JobExecutionContext context) {
       if (maybeSlug == null) {
         return;
       }
+      final @Nullable MonitorConfig monitorConfig =
+          shouldUpsertMonitorConfig(context) ? monitorConfigFromTrigger(context) : null;
       final @NotNull ISentryLifecycleToken lifecycleToken =
           scopes.forkedScopes("SentryJobListener").makeCurrent();
+      context.put(SENTRY_SCOPE_LIFECYCLE_TOKEN_KEY, lifecycleToken);
       TracingUtils.startNewTrace(scopes);
       final @NotNull String slug = maybeSlug;
       final @NotNull CheckIn checkIn = new CheckIn(slug, CheckInStatus.IN_PROGRESS);
+      checkIn.setMonitorConfig(monitorConfig);
       final @NotNull SentryId checkInId = scopes.captureCheckIn(checkIn);
       context.put(SENTRY_CHECK_IN_ID_KEY, checkInId);
       context.put(SENTRY_SLUG_KEY, slug);
-      context.put(SENTRY_SCOPE_LIFECYCLE_TOKEN_KEY, lifecycleToken);
     } catch (Throwable t) {
       scopes
           .getOptions()
@@ -84,6 +113,154 @@ public void jobToBeExecuted(final @NotNull JobExecutionContext context) {
     return null;
   }
 
+  private boolean shouldUpsertMonitorConfig(final @NotNull JobExecutionContext context) {
+    final @Nullable JobDataMap jobDataMap = context.getMergedJobDataMap();
+    if (jobDataMap == null) {
+      return true;
+    }
+    final @Nullable Object o = jobDataMap.get(SENTRY_UPSERT_MONITOR_CONFIG_KEY);
+    return o == null || !"false".equalsIgnoreCase(o.toString().trim());
+  }
+
+  private @Nullable MonitorConfig monitorConfigFromTrigger(
+      final @NotNull JobExecutionContext context) {
+    try {
+      final @Nullable Trigger trigger = context.getTrigger();
+      // Sentry can't express calendar exclusions
+      if (trigger == null || trigger.getCalendarName() != null) {
+        return null;
+      }
+      // each trigger would overwrite the others' schedule
+      if (hasSeveralTriggers(context)) {
+        return null;
+      }
+      if (trigger instanceof CronTrigger) {
+        final @NotNull CronTrigger cronTrigger = (CronTrigger) trigger;
+        final @Nullable String cron = toSixFieldCron(cronTrigger.getCronExpression());
+        if (cron == null) {
+          return null;
+        }
+        final @Nullable TimeZone timeZone = cronTrigger.getTimeZone();
+        return MonitorConfigUtils.fromSchedule(
+            cron, timeZone == null ? null : timeZone.getID(), null);
+      }
+      if (trigger instanceof SimpleTrigger) {
+        final @NotNull SimpleTrigger simpleTrigger = (SimpleTrigger) trigger;
+        if (simpleTrigger.getRepeatCount() != SimpleTrigger.REPEAT_INDEFINITELY) {
+          return null;
+        }
+        return MonitorConfigUtils.fromSchedule(null, null, simpleTrigger.getRepeatInterval());
+      }
+      return null;
+    } catch (RuntimeException | SchedulerException | NoSuchMethodError | AbstractMethodError e) {
+      // Trigger implementations may come from other Quartz versions or third parties
+      scopes
+          .getOptions()
+          .getLogger()
+          .log(
+              SentryLevel.WARNING, "Could not derive a monitor config from the Quartz trigger.", e);
+      return null;
+    }
+  }
+
+  private static boolean hasSeveralTriggers(final @NotNull JobExecutionContext context)
+      throws SchedulerException {
+    final @Nullable Scheduler scheduler = context.getScheduler();
+    final @Nullable JobDetail jobDetail = context.getJobDetail();
+    if (scheduler == null || jobDetail == null) {
+      return false;
+    }
+    return scheduler.getTriggersOfJob(jobDetail.getKey()).size() > 1;
+  }
+
+  /**
+   * Quartz numbers days of week 1-7 from Sunday; crontab uses 0-6. Null if a year is set or a name
+   * has a step.
+   */
+  static @Nullable String toSixFieldCron(final @Nullable String quartzCron) {
+    if (quartzCron == null) {
+      return null;
+    }
+    final @NotNull String[] fields = quartzCron.trim().split("\\s+", -1);
+    if (fields.length == 7 && !"*".equals(fields[6])) {
+      return null;
+    }
+    if (fields.length != 6 && fields.length != 7) {
+      return null;
+    }
+    if (NAME_STEP.matcher(fields[4]).find() || NAME_STEP.matcher(fields[5]).find()) {
+      return null;
+    }
+    final @Nullable String dayOfWeek = toZeroBasedDayOfWeek(fields[5]);
+    if (dayOfWeek == null) {
+      return null;
+    }
+    final @NotNull StringBuilder cron = new StringBuilder();
+    for (int i = 0; i < 5; i++) {
+      cron.append(fields[i]).append(' ');
+    }
+    return cron.append(dayOfWeek).toString();
+  }
+
+  private static @Nullable String toZeroBasedDayOfWeek(final @NotNull String field) {
+    final @NotNull StringBuilder result = new StringBuilder();
+    for (final @NotNull String item : field.split(",", -1)) {
+      final @Nullable String converted = toZeroBasedDayOfWeekItem(item.toUpperCase(Locale.ROOT));
+      if (converted == null) {
+        return null;
+      }
+      if (result.length() > 0) {
+        result.append(',');
+      }
+      result.append(converted);
+    }
+    return result.toString();
+  }
+
+  private static @Nullable String toZeroBasedDayOfWeekItem(final @NotNull String item) {
+    if (item.startsWith("*") || item.startsWith("?")) {
+      // '*' starts on Sunday in both
+      return item;
+    }
+    final int hash = item.indexOf('#');
+    if (hash >= 0) {
+      final @Nullable Integer day = toZeroBasedDay(item.substring(0, hash));
+      return day == null ? null : day + item.substring(hash);
+    }
+    if (item.length() > 1 && item.endsWith("L")) {
+      final @Nullable Integer day = toZeroBasedDay(item.substring(0, item.length() - 1));
+      return day == null ? null : day + "L";
+    }
+    final int slash = item.indexOf('/');
+    final @NotNull String days = slash >= 0 ? item.substring(0, slash) : item;
+    final @NotNull String step = slash >= 0 ? item.substring(slash) : "";
+    final @NotNull String[] range = days.split("-", -1);
+    if (range.length > 2) {
+      return null;
+    }
+    final @Nullable Integer start = toZeroBasedDay(range[0]);
+    if (start == null) {
+      return null;
+    }
+    if (range.length == 2) {
+      final @Nullable Integer end = toZeroBasedDay(range[1]);
+      return end == null ? null : start + "-" + end + step;
+    }
+    if (slash < 0 || start == 6) {
+      return String.valueOf(start);
+    }
+    // a step from a single day ends on Saturday in Quartz, but on Sunday (7) in crontab
+    return start + "-6" + step;
+  }
+
+  private static @Nullable Integer toZeroBasedDay(final @NotNull String day) {
+    if (day.matches("[1-7]")) {
+      return Integer.parseInt(day) - 1;
+    }
+    final int index = DAY_NAMES.indexOf(day);
+    return index >= 0 ? index : null;
+  }
+
   @Override
   public void jobExecutionVetoed(JobExecutionContext context) {
     // do nothing