timer

The timer block defines a named, scheduled pipeline that runs in the background. Each tick executes the timer's @execute pipeline. Timers run independently of inbound traffic handled by the servers block and are useful for periodic maintenance, polling, cache refresh, and similar background work.

Context

Top-level. A configuration may declare any number of timer blocks. Each timer has its own scheduler task and its own counters.

Syntax

timer "NAME" {
    interval <interval>;
    @execute {
        # pipeline body
    }
}

Parameters

"NAME"

Quoted string. Must be non-empty, must not contain ::, and must be unique across all timer blocks in the configuration.

interval

Any form accepted by interval:

• interval 5m; - fixed duration.
• interval "0 */5 * * * * *"; - seven-field cron expression.
• interval { duration 5m; random 30s; } - duration with +/- 15s jitter applied to each tick (random/2 on each side).
• interval { cron "0 0 * * * * *"; random 10s; } - cron with +/- 5s jitter applied to each tick.

The first tick fires after one full interval, not at configuration load. See Cron and interval timers for guidance on choosing between duration and cron forms and for usage patterns.

@execute

Standard pipeline body. Any actions valid in an @execute context are allowed (backend, set, log, if, try, sleep, etc.). The pipeline runs without an inbound request, so request-scoped attributes are not populated.

The pipeline result (accept, reject, ignore, error) controls counters but otherwise has no effect.

Validation

The configuration parser rejects:

• An empty timer name, or a name containing ::.
• Two timer blocks sharing the same name.
• A timer block missing interval or @execute.
• Multiple interval directives or multiple @execute blocks in one timer.
• The bare execute { ... } form: only @execute is accepted.
• time-zone set on a duration interval, or set to a value other than "local" or a valid IANA tz database name.

Examples

Periodic memory usage log

Sample stats counters every 30 seconds and emit them as a JSON record:

timer "MEMORY_STATS" {
    interval 30s;
    @execute {
        log "HEALTH" {
            json {
                "event" "memory_stats";
                "timestamp" datetime.timestamp;
                "process_rss_bytes" stats.process_rss_bytes;
                "system_mem_available_bytes" stats.system_mem_available_bytes;
            }
        }
    }
}

Cron schedule with jitter

Run daily at 02:00 in the host's local time zone with up to +/- 15s of jitter:

timer "DAILY_REPORT" {
    interval {
        cron "0 0 2 * * * *";
        random 30s;
    }
    @execute {
        backend "REPORT_GENERATOR";
    }
}

High-frequency polling

Run a short-lived poller several times per second. Keep the pipeline body short: if a tick is still running when the next one is due, the new tick is recorded as skipped rather than queued.

timer "POLL_FAST" {
    interval 100ms;
    @execute {
        backend "FAST_POLLER";
    }
}

Related

• interval - shared schedule syntax.
• Cron and interval timers - usage guide.
• Duration Units - accepted suffixes.
• aaa.policy.handler.@execute - execute pipeline syntax.