Skip to content

Spring Boot starter: @Scheduled and Quartz

The SilenceWatch Spring Boot starter monitors your application’s scheduled tasks without you declaring anything: it discovers every @Scheduled method and every Quartz job, declares them with their real schedule, and sends a heartbeat around every run. It is licensed under Apache 2.0, deliberately, so it can be embedded in any application.

  1. Get a SilenceWatch. Create an account at app.silencewatch.com, or self-host it.

  2. Create an API key in Settings › API keys › New key. It is shown once: copy it.

  3. Add the starter and the key (the installation below), and start your application with SILENCEWATCH_API_KEY set.

  4. Look at the log: SilenceWatch is watching 2 job(s). Every job is now in Checks, tagged auto, with its real schedule and a heartbeat at every run.

  5. Try it. Stop the application: the checks go late, then down. Add an alert channel in Alerting › New channel and use Send test to be told.

It needs Java 17 or later and scheduling switched on (@EnableScheduling, which your @Scheduled methods already need to run). It has been run against Spring Boot 3.5 and 4.1.

pom.xml
<dependency>
<groupId>com.silencewatch</groupId>
<artifactId>silencewatch-spring-boot-starter</artifactId>
<version>0.2.0</version>
</dependency>
build.gradle
implementation 'com.silencewatch:silencewatch-spring-boot-starter:0.2.0'
application.yml
silencewatch:
api-key: ${SILENCEWATCH_API_KEY}

Create the API key in your project’s Settings › API keys. That is the whole setup.

On ApplicationReadyEvent, in one HTTP call:

  • Spring: it reads the tasks Spring itself scheduled, so the schedules are the resolved ones: @Scheduled(cron = "${backup.cron}") is declared with the expression the property actually held.
  • Quartz: if Quartz is present, it iterates the jobs and reads their triggers. A job with several triggers is declared from the one that fires most often, since that is the deadline a missed run breaches first.
  • It declares everything to POST /api/v1/checks/sync and keeps the returned ping keys in memory.

Each job gets a stable identity that ties it to its history across restarts, redeployments and renames: com.acme.jobs.BackupJob#run for Spring, group.jobName for Quartz. A job that disappears from the code is flagged orphaned, never deleted.

A Spring AOP advisor (plain Spring AOP, no AspectJ) wraps every @Scheduled method; a JobListener does the same for Quartz:

POST /p/<key>/start when the run begins
POST /p/<key>/0?duration_ms=1234 when it returns
POST /p/<key>/fail?duration_ms=1234 when it throws
silencewatch:
enabled: true # false removes everything, see below
api-key: ${SILENCEWATCH_API_KEY}
base-url: https://app.silencewatch.com # your own instance when self-hosting
environment: production # part of a check's identity
default-grace: 5m # for jobs that declare none
auto-register: true # false to manage checks by hand
report-start: true # false to send only the outcome
timeout: 2s # per call, deliberately short
queue-capacity: 1000 # bounded, oldest dropped when full
timezone: Europe/Paris # for cron jobs whose trigger carries none
discover-spring-tasks: true
discover-quartz-jobs: true
per-instance-jobs: com.acme.cache.LocalCache#evict # see "Several instances" (0.2.0)
instance-id: ${HOSTNAME} # with per-instance-jobs only, and stable

When an application runs as several instances (replicas, pods, servers), they all declare the same jobs in the same environment, so each job is one check for all of them: it is up while any instance reports it. That is what most jobs should be held to:

  • a clustered Quartz job, or a @Scheduled method behind a lock (ShedLock), runs on one instance at a time, and whichever one it is, the check hears from it. With ShedLock, only the instance that got the lock reports the run (from starter 0.2.1: earlier versions also reported the runs the other instances skipped, which could hide a stuck job). Leave @EnableSchedulerLock’s order at its default; the starter warns if it cannot sit inside the lock;
  • a @Scheduled method without a lock runs on every instance. The check stays up as long as one of them runs it, so an instance whose scheduler is stuck goes unnoticed while another works. If the job should run once, put it behind a lock; if it has to run everywhere, read on.

Jobs that have to run on every instance (clearing a local cache, deleting temporary files) can be monitored on each one, from starter 0.2.0:

silencewatch:
per-instance-jobs:
- com.acme.cache.LocalCache#evict
- com.acme.tmp.* # a trailing * matches a prefix
instance-id: ${HOSTNAME}

Those jobs are declared in an environment of the instance’s own, production.app-0, so each instance has its own check and one going quiet is seen while the others report. Every other job stays shared.

instance-id has no default, and must stay the same across restarts and deploys: a StatefulSet pod’s name, a server’s hostname. A Deployment’s pod names change at every rollout, which would leave behind, each time, checks nobody reports to any more, and they would go down. Without instance-id, the listed jobs are watched as shared, with a warning. When you remove an instance for good (scaling a StatefulSet down), delete its checks.

These are what make it safe to put in a production application:

  • It never fails your job. Every network or HTTP error is swallowed and logged at WARN. The interceptor calls your method exactly once, returns its result untouched, and rethrows its exception unchanged.
  • It never blocks your job. Sending a heartbeat is a queue offer handled by a low-priority daemon thread. An unreachable SilenceWatch costs your job nothing.
  • It is bounded. The queue holds at most queue-capacity heartbeats; past that the oldest are dropped, because the freshest state is the one worth reporting. Warnings are limited to one a minute.
  • It degrades silently. No API key, no network, no server: the application starts and runs exactly as it would without the dependency.
  • silencewatch.enabled: false removes the mechanism entirely: no discovery, no proxying, no threads, no beans.
  • No heavy dependencies. spring-boot-starter plus the JDK HTTP client. No JSON library, so no Jackson version is forced on your application.
  • Sub-30-second jobs are declared with a 30-second period, the shortest accepted, and a warning names them.
  • Quartz’s W cannot be evaluated by the server, so those jobs are skipped with a warning rather than failing the whole declaration.
  • Programmatically scheduled tasks (SchedulingConfigurer, lambdas) have no stable identity and are ignored. Declare those checks by hand, or give them a @Scheduled method.
  • spring.aop.auto=false disables the proxying Spring Boot normally provides: jobs are declared but no heartbeat can be sent. The starter says so at startup.