Add JitteredCronTimetable for deterministic schedule jitter

[Pebble32]

Add JitteredCronTimetable, an opt-in CronTriggerTimetable subclass that shifts each DAG's fire time by a deterministic, per-DAG offset drawn from [0, max_jitter). This spreads out DAGs that share a cron expression so they no longer all fire at the same instant, without changing logical_date / data_interval semantics.

Why

@daily expands to 0 0 * * *, so every daily DAG in a deployment is scheduled at exactly midnight. In large deployments this "thundering herd" at the cron boundary overloads the scheduler and workers — enough to cause task failures when dozens of DAGs are born at the same instant.

The existing ways to deal with this don't actually de-collide the schedule:

Existing option	Why it doesn't solve the problem
Hand-pick a unique minute per DAG	Manual, doesn't scale, drifts and re-collides as DAG count grows, and throws away the @daily intent
Hash the DAG id into a literal cron string	Same loss of intent; not reusable across DAGs/teams; every author re-implements it ad hoc
Pools / concurrency limits (parallelism, max_active_tasks_per_dag, pool slots)	These limit or queue execution — the runs are still scheduled at the same instant. They cap contention downstream but never spread the fire times apart at the source.

JitteredCronTimetable is the only approach that moves the fire times themselves, deterministically: the same seed (e.g. the DAG id) always maps to the same offset, so runs stay stable and predictable across scheduler restarts and timetable serialization. Motivated by the discussion in #69027.

What

• New JitteredCronTimetable(CronTriggerTimetable) in both the Task SDK (author-facing, attrs-based) and airflow-core (scheduler-side), plus the serialization wiring (BUILTIN_TIMETABLES mapping, serialize/deserialize, encode/decode across the SDK↔core boundary).
• Two extra kw-only params on top of CronTriggerTimetable: seed: str and max_jitter: timedelta.
• The offset is md5(seed) % max_jitter.total_seconds(), applied as a "strip → cron → apply" coordinate shift so cron/DST alignment is fully delegated to the parent and only the wall-clock fire time is shifted.
• Fully opt-in and safe by default: with the defaults (seed="", max_jitter=timedelta(0)) the offset is zero and it behaves identically to CronTriggerTimetable. Nothing changes for anyone who doesn't use it.

Tests

airflow-core/tests/unit/timetables/test_jittered_cron_timetable.py, modeled on the existing test_trigger_timetable.py:

• jittered runs equal base cron runs shifted by the fixed offset, across a catchup sequence including a DST spring-forward (America/New_York);
• zero max_jitter reproduces CronTriggerTimetable exactly (catchup on/off);
• offsets are deterministic for a given seed, bounded to [0, max_jitter), and spread across distinct seeds;
• serialize/deserialize round-trips seed + window + derived offset;
• full encode → decode round-trip across the SDK/core layers rebuilds the core class.

---

Was generative AI tooling used to co-author this PR?

• Yes (please specify the tool below)

Generated-by: Claude (Claude Code), following the guidelines

---

related: #69027

[boring-cyborg]

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contributors' Guide
Here are some useful points:

• Pay attention to the quality of your code (ruff, mypy and type annotations). Our prek-hooks will help you with that.
• In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example Dag that shows how users should use it.
• Consider using Breeze environment for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
• Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
• Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
• Be sure to read the Airflow Coding style.
• Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related to your commits.
  Apache Airflow is a community-driven project and together we are making it better 🚀.
  In case of doubts contact the developers at:
  Mailing List: dev@airflow.apache.org
  Slack: https://s.apache.org/airflow-slack

[uranusjr]

I wonder if it’d make sense to add this functionality directly to CronMixin (and therefore inherited by all cron-based scheduling). Some scheduling tools (Jenkins IIRC) have this built-in for cron scheduling (opt-in) to not let a large number of jobs spiking a server periodically if timing is not essential.

Implementation seems reasonable to me in general.

[Pebble32]

Thanks @uranusjr! The Jenkins H comparison is exactly the idea

I kept it as its own timetable to keep the change contained. Moving it into CronMixin means every cron timetable (data interval, multiple cron, partition) also needs its serialization and logical_date behavior worked out, so the scope grows quite a bit.

Would you prefer I land this focused version first and generalize into CronMixin as a follow up, or go straight for CronMixin now? Happy either way, just trying to keep the PR reviewable <3

[raphaelauv]

hey about "enough to cause task failures"

if it can happen then it will happen again ( backfill , new dags , big clear ... )

your tasks fail because you did not put correct/perfect limit on concurrency.

I know it's not easy :

yes airflow pools are too simple for many use-case

yes airflow is not kubernetes ressource aware ( he do not know your max hardware scaling limits and don't queue tasks regarding this )

---

"but never spread the fire times apart at the source."

I've a stack triggering more than a thousand of dag_run at midnight , yes it take almost 30 seconds to the scheduler to do so , but no errors , did you encounter a scheduler error ?

[Pebble32]

Fair point, and well put. Where I still think it earns its place is as peak shaving on top of concurrency limits, not instead of them: spreading arrivals so fewer tasks land in the pool at the same instant, so a fixed pool saturates less often. Opt in, for when exact timing does not matter. Same idea as Jenkins H that @uranusjr mentioned. Maybe it is better to move it directly to CronMixin

[uranusjr]

Can you explore this locally to see how intrusive adding this would be? If implementation becomes messy, I think it’s reasonable to do this in a separate timetable in this PR first with the intention to eventually refactor the logic into CronMixin before 3.4.0 is released, which is quite still some time away.

[Pebble32]

Sounds good. I will explore the CronMixin version locally and report back on how intrusive it looks.

[Pebble32]

Explored it and it seems less intrusive than I first thought. The offset moves into CronMixin cleanly, and on the sdk side the fields are inherited by all cron timetables. The rest is mechanical, forwarding seed and max_jitter through the core constructors and the per class serialize, deserialize and encoder variants.

For CronDataIntervalTimetable the shared offset shifts both interval bounds and the fire time by the same amount, so the window stays one full period long but sits offset from the cron line (00:35 to 00:35 instead of 00:00 to 00:00), and consecutive runs stay contiguous so no gaps or overlaps. I will go with that uniform shift as the default and document it, keeping the guidance to set max_jitter small relative to the period. Jittering only the fire time while keeping the interval on the cron boundary is possible but needs a targeted override, so I will leave it as a possible follow up.

Will put up the CronMixin version.

[Pebble32]

Follow up moving the jitter into CronMixin as discussed: #72475. Will close this PR once that one lands.

[Pebble32]

@uranusjr the CronMixin version we discussed is up in #72475 and CI is green. Would appreciate a look whenever you have a moment. Thanks!