Skip to content

Add dag.schedule_overdue_seconds metric for Dags held back by max_active_runs - #74854

Open
Abdel39 wants to merge 5 commits into
apache:mainfrom
Abdel39:aboulfoul/schedule-overdue-seconds-metric
Open

Abdel39 wants to merge 5 commits into
apache:mainfrom
Abdel39:aboulfoul/schedule-overdue-seconds-metric

Conversation

@Abdel39

@Abdel39 Abdel39 commented Oct 16, 2026

Copy link
Copy Markdown
Contributor

related: #73686

When a time-scheduled Dag is at max_active_runs, DagModel.dags_needing_dagruns filters it out (exceeds_max_non_backfill == false), so its next run is never created. Nothing is queued, scheduler.dagruns.queued (#70013) stays at zero, and nothing tells you the Dag is falling behind its schedule until someone notices missing intervals.

This adds a dag.schedule_overdue_seconds gauge, tagged by dag_id: seconds since the Dag's next_dagrun_create_after, emitted only while the Dag is due and held back by max_active_runs.

  • Emitted on the existing [scheduler] dagrun_metrics_interval timer, as a separate read-only query. It does not touch dags_needing_dagruns, which is row-locked and LIMITed.
  • Only Dags in the blocked state are emitted, so the series count is bounded by the number of blocked Dags, not the number of Dags. A healthy deployment emits nothing.
  • Asset-gated Dags are excluded, since next_dagrun_create_after alone does not make them due.

We've run the same metric as a scheduler patch on our Airflow staging deployments. It was the signal teams needed to decide when to raise max_active_runs for scheduled Dags, where queued-run counts showed nothing.


Was generative AI tooling used to co-author this PR?
  • Yes -- Claude Opus 5.5

Generated-by: Claude Opus 5.5 following the guidelines

@boring-cyborg

boring-cyborg Bot commented Oct 16, 2026

Copy link
Copy Markdown

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

Abdel39 added a commit to Abdel39/airflow that referenced this pull request Oct 16, 2026
@Abdel39
Abdel39 marked this pull request as ready for review October 16, 2026 14:20

@hussein-awala hussein-awala left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After recovery, the query excludes the Dag. The method sends no further value for that Dag. By default, StatsD keeps the last gauge value. Thus, an alert can remain active after recovery.

Please send zero for each previously reported Dag absent from the next query result. Use the existing reset pattern in _emit_ti_metrics.

Add a regression test with these steps:

  1. Collect the metric for a blocked Dag.
  2. Clear exceeds_max_non_backfill.
  3. Collect the metric again.
  4. Check for a zero value in the second collection.

@hussein-awala hussein-awala left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, LGTM

@hussein-awala hussein-awala added the ready for maintainer review Set by triage when all criteria pass, or by the fork CI reconciler when fork CI is green. label Oct 23, 2026
@hussein-awala hussein-awala added this to the Airflow 3.4.0 milestone Oct 23, 2026
@hussein-awala hussein-awala added the backport-to-v3-4-test Backport to v3-4-test label Oct 23, 2026
Abdel39 and others added 5 commits November 6, 2026 11:03
…ive_runs

When a time-scheduled Dag is at max_active_runs, dags_needing_dagruns
skips it, so its next run is never created and nothing is queued. No
metric shows that the Dag is falling behind its schedule.

Emit dag.schedule_overdue_seconds{dag_id} on the dagrun_metrics_interval
timer, only for Dags in that state, so the number of series is bounded
by the number of blocked Dags.

Generated-by: Claude Opus 5.5 following the guidelines
StatsD keeps a gauge's last value, so a Dag that left the blocked state
kept reporting its last lateness. Send zero once for Dags reported on the
previous run but absent now, following the _emit_ti_metrics pattern.
dag.schedule_overdue_seconds and the per-dag_id scheduler.dagruns.running
and scheduler.dagruns.queued gauges are emitted from scheduler queries with
a hand-built dag_id tag, so they never go through DagRun.stats_tags and
miss the Dag tags that [metrics] dag_tags_in_metrics adds elsewhere.

Look the tags up in one DagTag query per emission and merge them the same
way DagRun.stats_tags does. The zero reset for recovered Dags reuses the
tags it emitted, so it lands on the same series.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Abdel39
Abdel39 force-pushed the aboulfoul/schedule-overdue-seconds-metric branch from ff83f48 to e9e2877 Compare November 6, 2026 16:05

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:scheduler backport-to-v3-4-test Backport to v3-4-test ready for maintainer review Set by triage when all criteria pass, or by the fork CI reconciler when fork CI is green.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants