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.
Quick start
Section titled “Quick start”-
Get a SilenceWatch. Create an account at app.silencewatch.com, or self-host it.
-
Create an API key in Settings › API keys › New key. It is shown once: copy it.
-
Add the starter and the key (the installation below), and start your application with
SILENCEWATCH_API_KEYset. -
Look at the log:
SilenceWatch is watching 2 job(s). Every job is now in Checks, taggedauto, with its real schedule and a heartbeat at every run. -
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.
Installation
Section titled “Installation”<dependency> <groupId>com.silencewatch</groupId> <artifactId>silencewatch-spring-boot-starter</artifactId> <version>0.2.0</version></dependency>implementation 'com.silencewatch:silencewatch-spring-boot-starter:0.2.0'silencewatch: api-key: ${SILENCEWATCH_API_KEY}Create the API key in your project’s Settings › API keys. That is the whole setup.
What it does at startup
Section titled “What it does at startup”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/syncand 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.
What it does at run time
Section titled “What it does at run time”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 beginsPOST /p/<key>/0?duration_ms=1234 when it returnsPOST /p/<key>/fail?duration_ms=1234 when it throwsConfiguration
Section titled “Configuration”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 stableSeveral instances
Section titled “Several instances”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
@Scheduledmethod 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’sorderat its default; the starter warns if it cannot sit inside the lock; - a
@Scheduledmethod 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.
Rules it will not break
Section titled “Rules it will not break”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-capacityheartbeats; 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: falseremoves the mechanism entirely: no discovery, no proxying, no threads, no beans.- No heavy dependencies.
spring-boot-starterplus the JDK HTTP client. No JSON library, so no Jackson version is forced on your application.
Limits
Section titled “Limits”- Sub-30-second jobs are declared with a 30-second period, the shortest accepted, and a warning names them.
- Quartz’s
Wcannot 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@Scheduledmethod. spring.aop.auto=falsedisables the proxying Spring Boot normally provides: jobs are declared but no heartbeat can be sent. The starter says so at startup.