Skip to content

Add Real-World DAG Debugging Strategies to Airflow Docs #71948

Open

Description

@jroachgolf84

Description

Right now, most of the documentation around debugging Airflow DAGs references dag.test() and the command line. While this is a viable way to debug DAGs, it's not typically the way that it is done at the enterprise-level.

Update this docs page to include more "practical" or E2E testing techniques for DAGs. This might include running a Task and inspecting its XComs. Or re-running a single Task via the UI to validate that it ran successfully. There are tons of ways that this is done!

Existing Docs: https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/debug.html

Are you willing to submit a PR?

  • Yes I am willing to submit a PR!

Code of Conduct

Activity

  1. self-assigned this
    on Aug 22, 2026
  2. jroachgolf84 commented on Aug 30, 2026

    @jroachgolf84
    CollaboratorAuthor

    This is an issue that is reserved for the Airflow Summit "Contributors" Workshop. This is denoted with the label contributors-workshop. Out of respect for the organizers and participants of this workshop, please do not implement a PR that addresses this issue.

    If this issue is still open following Airflow Summit, the label will be removed and the issue can be picked up.

  3. removed their assignment
    on Sep 2, 2026
  4. jroachgolf84 commented on Sep 2, 2026

    @jroachgolf84
    CollaboratorAuthor

    This issue is now open for contribution. Please feel free to create a PR!

  5. BaconMan1168 commented on Sep 3, 2026

    @BaconMan1168

    Thanks for reopening this, @jroachgolf84 — I'd like to pick it up. Before writing anything, here's the outline I'm planning to add to debug.rst, since the exact scope wasn't pinned down in the issue:

    New sections after the existing "Debugging Dags on the command line" section:

    1. Inspecting XComs during a DAG run — pulling a task's XCom values for a specific run from the Grid view's XCom tab and via the CLI, with a pointer to the dedicated :doc:XComs <xcoms> page for the underlying concept.
    2. Re-running a single task from the UI — clearing a task instance from the Grid view to re-trigger it in place, and when to reach for "Clear" vs "Mark as failed/success".
    3. Testing a single task from the CLI — airflow tasks test <dag_id> <task_id> <logical_date> as a lighter-weight, single-task alternative to dag.test() when iterating on just one task.

    I'm keeping this scoped to what's directly actionable on this page rather than duplicating the dedicated XComs/UI docs. Let me know if this matches what you had in mind, or if there's a different technique you'd rather see prioritized, and I'll get started.

  6. lry624 commented on Sep 5, 2026

    @lry624

    Hi, I'd like to work on this. Planned scope: a single new section in airflow-core/docs/core-concepts/debug.rst — "Debugging Dags in a deployed environment" — covering inspecting task instances from the Grid view (Logs / XComs tabs, linking to the existing XComs page) and via the CLI (airflow tasks state, failed-deps, render), plus re-running a single task with airflow tasks test and airflow tasks clear (--task-regex, --start-date/--end-date, --downstream).

  7. jroachgolf84 commented on Sep 8, 2026

    @jroachgolf84
    CollaboratorAuthor

    I posted this in the PR, but putting it here as well:

    IMO, this is not very "real-world" debugging strategies. I'm thinking of a more "tricks of the trade" approach. For example:

    • Looking through Task logs (filtering by log-level)
    • Searching logs
    • Looking at XComs
    • Validating that Connections and/or Variables exist
    • Looking back through historic Task runs

    What is currently here is NOT real-world.

  8. adiranjan25 commented on Sep 30, 2026

    @adiranjan25
    Contributor

    Hi @jroachgolf84, I'd like to work on this issue.
    I'm interested in expanding the debugging documentation with practical, production-oriented troubleshooting workflows, including task-state investigation, logs and XCom inspection, dependency and trigger-rule diagnosis, queued-task/resource-constraint scenarios, and safe task rerun/validation techniques through the Airflow UI.
    I'll keep the contribution focused on actionable debugging workflows that complement the existing dag.test() and command-line guidance.
    Please let me know if this scope aligns with what you had in mind. Thanks!

  9. seyiogunjuyigbe commented on Nov 3, 2026

    @seyiogunjuyigbe

    #72571 has had no update since the 09-08 review, and #74468 covers a few UI steps. I've opened #76367 with the scope from that review: filtering and searching task logs, picking a try, XComs, checking Connections and Variables (including ones from a secrets backend), comparing past runs, clearing a single task, and airflow tasks test. If #72571 picks back up, I'm happy to fold this into it instead.

  10. adiranjan25 commented on Nov 4, 2026

    @adiranjan25
    Contributor

    Hi @jroachgolf84 and @seyiogunjuyigbe,

    Thanks for the update and for coordinating the documentation improvements.

    I see that PR #76367 now covers much of the practical debugging guidance I was interested in contributing.

    To avoid duplicating existing work, I'd be happy to help with a complementary area, particularly troubleshooting tasks stuck in queued or scheduled states, worker capacity constraints, task dependencies, and trigger-rule behavior in production deployments.

    Would these topics be useful as a separate, focused documentation contribution, or would you prefer that I help review and validate the existing PR?

    I'm happy to follow whichever approach would be most helpful to the project.

    Thanks!

  11. Jasim-svg commented on Nov 9, 2026

    @Jasim-svg

    Hi everyone!

    I'm a DevOps and AI Engineer, and I'm interested in making my first contribution to Apache Airflow.

    I came across this issue and found the idea of adding practical, production-oriented DAG debugging strategies particularly useful.

    I'd like to contribute a focused documentation section covering areas such as:

    • Searching and filtering task logs.
    • Validating Airflow Connections and Variables.
    • Investigating historical task runs.
    • Practical troubleshooting workflows for failed tasks.

    I noticed there have already been discussions around the proposed scope, so I wanted to check whether this issue is still open for another contributor and whether there's a specific area that needs help.

    I'm happy to coordinate with the existing contributors to avoid duplicating work.

    Looking forward to contributing!

  12. adiranjan25 commented on Nov 10, 2026

    @adiranjan25
    Contributor

    Hi @Jasim-svg, welcome to the Apache Airflow community!

    Thanks for your interest in contributing to this issue. Practical DAG troubleshooting is an important area, and it's great to see more contributors interested in improving the documentation.

    Just to help avoid overlapping work, PR #76367 already covers several of the topics you've mentioned, including log inspection, Connections and Variables, XComs, and historical task runs. There are also related contributions in PRs #72571 and #74468.

    I had previously expressed interest in this issue and proposed a complementary documentation contribution focused on diagnosing tasks stuck in queued or scheduled states, worker capacity constraints, task dependencies, and trigger-rule behavior in deployed environments.

    I think there's room for us to collaborate effectively by keeping these areas clearly separated.

    @jroachgolf84, would you be able to advise on the preferred scope and whether these remaining troubleshooting scenarios would be useful as a separate contribution?

    Happy to coordinate with everyone to ensure we deliver useful, non-duplicative improvements to the Airflow documentation.

    Thanks!
    Aditya

  13. galiliya commented on Nov 10, 2026

    @galiliya

    I'd keep the queued/scheduled material separate from debug.rst — that's really scheduler and executor capacity territory, and folding it into the debugging page would blur what the page is for. Worth checking first whether the executor/scheduler docs already touch on queued tasks so you're extending them rather than repeating them. In the meantime, reviewing #76367 is genuinely useful; the UI steps are the easiest part to get subtly wrong and nobody has re-checked them against current 3.x screens. Which of the two do you want to take first?

  14. adiranjan25 commented on Nov 10, 2026

    @adiranjan25
    Contributor

    Hi @galiliya,

    Thank you for the guidance. I agree that queued/scheduled task troubleshooting belongs in the scheduler/executor documentation rather than debug.rst.

    I'd like to start with a technical review of PR #76367, focusing on the accuracy and reproducibility of the debugging workflows against Airflow 3.x, particularly UI navigation, task logs, XCom inspection, and safe task rerun procedures.

    I also noticed that PR #76811 has now been opened against the same issue with overlapping scope. Would you recommend prioritizing #76367 or reviewing both PRs to help identify gaps and avoid duplication?

    Once the review is completed, I'd be happy to investigate the existing scheduler/executor documentation and propose a separate, focused contribution addressing any remaining troubleshooting gaps.

    Thanks for helping coordinate this effort.

    Best regards,
    Aditya

  15. Jasim-svg commented on Nov 11, 2026

    @Jasim-svg

    Hi everyone,

    Thanks for the guidance.

    I'd like to start with a technical review of PR #76367.

    I'll focus on independently validating the documentation against Airflow 3.x, particularly the CLI examples, task debugging workflows, UI navigation and production safety considerations.

    I noticed some existing review feedback around task-clearing semantics and deprecated CLI commands, so I'll avoid duplicating those observations and focus on identifying any additional gaps.

    Once I've completed the review, I'd be interested in exploring the scheduler/executor documentation for a separate contribution covering queued and scheduled task troubleshooting.

    Looking forward to learning and contributing to the Airflow community!

    Best regards,
    Muhammad Jasim

  16. adiranjan25 commented on Nov 12, 2026

    @adiranjan25
    Contributor

    Hi @Jasim-svg,

    Thanks for coordinating and for taking care to avoid duplicating the existing technical review feedback.

    I've already completed an initial technical review of PR #76367, including findings on deprecated CLI commands, task-clearing semantics, and production safety considerations.

    As discussed earlier, I'm interested in a separate, focused documentation contribution addressing tasks stuck in queued or scheduled states, scheduler/executor capacity constraints, dependency troubleshooting, and trigger-rule diagnostics.

    I'll first review the existing scheduler/executor documentation to identify specific gaps.

    @galiliya @jroachgolf84 — would you recommend opening a separate issue for this scope once those gaps are identified?

    Happy to coordinate to keep contributions complementary and avoid overlapping work.

    Thanks!

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions