Project challenges / verified progress
Beacon: turn a program into a service

The engineering notebook

Run checks on schedule

How does a service repeat work without lying about time?

Loading Vault account...
Phase 1 — Time and input

Step 01 of 06

Understand the idea

A one-time check gives you one result. A service repeats checks on a schedule. This lesson explains how to keep that schedule predictable and prevent slow checks from piling up.

ONE MINUTE WITH JITTERsecondsWaitbase interval55sJitterrandom spread+4sCheckbounded work900ms
The nominal interval is one minute, but each cycle gets a small random offset. Ten thousand agents that all started at 09:00 no longer hit the same target at exactly 09:01. That is the whole trick, and it saves real systems.
Step 01

Key technical ideas

A ticker keeps the cadence outside the work

time.NewTicker(time.Minute) signals once each minute. The next signal follows the clock, even if the previous check took time. With time.Sleep(interval) after each check, the wait starts only after the work ends. For example, a 10-second check followed by a 60-second sleep runs every 70 seconds.

Slow work needs a stated policy

Suppose checks should start every 30 seconds, but one check takes 45 seconds. Decide what happens when the next start time arrives: skip it, cancel the current check, or allow a limited number of checks to overlap. Without a limit, slow checks can keep starting new goroutines and use too much memory and too many connections.

Jitter prevents a thundering herd

A thundering herd is a burst of requests from many workers at the same time. It can happen when services all start together and use the same schedule. Jitter adds a small random delay to each schedule. This spreads out the requests; for a 60-second interval, a 6-second jitter window can reduce the burst.

The loop must stop on context cancellation

A service needs to stop when it receives a shutdown request. If the scheduler waits only for its next ticker signal, it may not notice the request right away. Waiting for either the ticker or ctx.Done() lets it stop promptly. Passing the context to a running check also gives that check a chance to stop its network requests.

A loop that skips while busy
package main

import (
	"context"
	"fmt"
	"time"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	ticker := time.NewTicker(100 * time.Millisecond)
	defer ticker.Stop()

	busy := false
	for i := 0; i < 3; i++ {
		select {
		case <-ctx.Done():
			return
		case at := <-ticker.C:
			if busy {
				fmt.Println("skip", at.Format("15:04:05"))
				continue
			}
			busy = true
			fmt.Println("run", i)
			busy = false
		}
	}
}

This tiny loop shows the policy in the open: if work is already busy, the next tick is skipped. Real Beacon will put check execution behind a function, but the scheduler still needs this kind of explicit choice instead of accidental goroutine growth.

Ticker and sleep do different jobs

MechanismWhat it measuresRisk

time.Ticker

Clock cadence

Ticks can pile up if ignored

time.Sleep after work

Delay after completion

Work time becomes drift

time.Timer

One future event

Must reset carefully

Cron

Wall-clock schedule

Overkill inside one service

Technical terms used at work

  • Cadence — The intended rhythm of recurring work, such as every 60 seconds.

  • Drift — The schedule sliding later because work duration is added to the delay.

  • Jitter — A small random offset added to a schedule to spread load.

  • Thundering herd — Many clients waking together and overwhelming a dependency.