Docs › Spring @Scheduled monitoring with RunVouch

Spring @Scheduled monitoring with RunVouch

Spring @Scheduled monitoring for the log line nobody grepped: @Scheduled(cron = "0 0 2 * * *") runs inside the application. An exception is caught by the scheduler's error handler, logged at ERROR, and the next fire proceeds as planned. A method that hangs on a socket blocks the default one-thread scheduler and every other task with it.

How it runs on Spring @Scheduled

At the top and bottom of the scheduled method with Java's built-in HttpClient (Java 11+), or in a small @Aspect around every @Scheduled method if you have many. Register the agent's cadence once.

Store the key

RUNVOUCH_KEY as an environment variable read through @Value("${RUNVOUCH_KEY}") or application.yml with a placeholder; Spring Cloud Config or Vault if you have them.

Report the run (two HTTP calls)

@Component
public class NightlyReport {
  private static final String API = "https://api.runvouch.com";
  private final HttpClient http = HttpClient.newHttpClient();
  private final ObjectMapper json = new ObjectMapper();
  @Value("${RUNVOUCH_KEY}") String key;

  private Map<String, Object> post(String path, Map<String, Object> body) {
    try {
      var req = HttpRequest.newBuilder(URI.create(API + path)).timeout(Duration.ofSeconds(10))
          .header("X-API-Key", key).header("content-type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(json.writeValueAsString(body))).build();
      return json.readValue(http.send(req, HttpResponse.BodyHandlers.ofString()).body(), Map.class);
    } catch (Exception e) { return Map.of(); }   // fail open: the job still runs
  }

  @Scheduled(cron = "0 0 2 * * *", zone = "UTC")
  public void run() {
    String runId = (String) post("/v1/runs/start", Map.of("agent", "nightly-report", "source", "spring")).get("run_id");
    try {
      int rows = reportService.build();                     // your work
      post("/v1/runs/end", Map.of("run_id", runId, "status", "ok", "evidence", Map.of("rows_written", rows > 0)));
    } catch (Exception e) {
      post("/v1/runs/end", Map.of("run_id", runId, "status", "fail", "meta", Map.of("error", e.toString())));
      throw e;
    }
  }
}
// @EnableScheduling on a configuration class; rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence

The start call returns run_id; the end call takes status (ok or fail), optional cost and tokens, and evidence as a JSON object of booleans. Full reference on the API page.

Register the cadence and caps

rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence --cap-run-cost 2

Register the agent once, from anywhere with the key. Cadence is what turns a schedule that stopped into an alert; --evidence makes a run without evidence a failure; the caps pause the agent when it overspends.

What goes silent on Spring @Scheduled

• The default TaskScheduler has one thread. A task blocked on a slow HTTP call without a timeout blocks every other @Scheduled method; the blocked one is STALLED, the others are MISSED, and the app's health endpoint says UP.
• Exceptions are handled by the scheduler's ErrorHandler (logged) and the schedule continues; nothing is thrown to anything that would page you.
• No catch-up: a fire time that passes while the app is restarting is skipped.
• Two instances of the app run the task twice unless you add ShedLock or similar; both runs are visible under one agent.

What Spring @Scheduled does not tell you

Spring logs a scheduled task's exception at ERROR level through the default error handler and moves on; Actuator's /actuator/scheduledtasks lists the schedules, not their outcomes, and Micrometer only measures what you instrument. Nothing in the framework knows that 02:00 came and went with the app down, or that the method returned after writing an empty file.

What RunVouch detects

Set up in two minutes

1. Get a free key (3 agents, no card) and store it where this page says.
2. report the run (two http calls): copy the snippet above into the scheduled job.
3. Register the cadence once: rv agent nightly-report --cadence 24h --grace 30m --evidence, or let the first run create the agent and set the cadence on the dashboard.
4. Send one test alert: curl -X POST https://api.runvouch.com/v1/settings/test-alert -H "X-API-Key: $RUNVOUCH_KEY". The next missed, failed or empty run reaches the same channels.

Also running orchestrators?

Quartz Scheduler. Apache Airflow. Prefect. Dagster. The full list of runtimes is on integrations, and the same agent can report from several of them: one job, one cadence, wherever it happens to run.

Need a key? Get a free key · Stuck? contact