Skip to content

docs: Added guide on debugging workflows#4029

Merged
johanneskoester merged 15 commits into
mainfrom
docs/how-to-guide-for-debugging
May 22, 2026
Merged

docs: Added guide on debugging workflows#4029
johanneskoester merged 15 commits into
mainfrom
docs/how-to-guide-for-debugging

Conversation

@mrmattuschka

@mrmattuschka mrmattuschka commented Mar 10, 2026

Copy link
Copy Markdown
Contributor

Closes #4013 .

Added a docs page on debugging workflows:

  • log file locations
  • faster DAG resolution
  • interactive debugging
  • preserving script rule wrapper scripts

QC

  • The PR contains a test case for the changes or the changes are already covered by an existing test case.
    Not applicable - only documentation affected
  • The documentation (docs/) is updated to reflect the changes or this is not necessary (e.g. if the change does neither modify the language nor the behavior or functionalities of Snakemake).

Summary by CodeRabbit

  • Documentation
    • Added a comprehensive debugging guide: locating main and per-job logs, redirecting STDERR in Python and R with examples, enabling improved R backtraces, speeding DAG resolution by targeting outputs, preserving generated wrapper scripts, and using Snakemake’s debug flags for interactive investigation.
    • Linked the new debugging guide from the main documentation index.

<!--Add a description of your PR here-->

Added a docs page on debugging workflows:
- log file locations
- faster DAG resolution
- interactive debugging

### QC
<!-- Make sure that you can tick the boxes below. -->

* [ ] The PR contains a test case for the changes or the changes are
already covered by an existing test case.
**Not applicable - only documentation affected**
* [X] The documentation (`docs/`) is updated to reflect the changes or
this is not necessary (e.g. if the change does neither modify the
language nor the behavior or functionalities of Snakemake).
@mrmattuschka mrmattuschka linked an issue Mar 10, 2026 that may be closed by this pull request
@coderabbitai

coderabbitai Bot commented Mar 10, 2026

Copy link
Copy Markdown
Contributor

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds a new documentation page on debugging Snakemake workflows and registers it in the docs index under "Defining workflows". The page documents log locations, per-job logs, STDERR redirection for scripts, R backtraces, DAG-targeted runs, VS Code debugging setup, breakpoints, and preserving wrapper scripts.

Changes

Cohort / File(s) Summary
Documentation Index
docs/index.rst
Inserted snakefiles/debugging_workflows into the "Defining workflows" toctree.
Debugging Guide
docs/snakefiles/debugging_workflows.rst
Added new guide covering main run log location (.snakemake/log/), executor-specific job logs, redirecting STDERR from script rules (examples for Python and R), enabling improved R backtraces, targeting a specific rule output to speed DAG resolution, VS Code Python debugger launch config and breakpoint guidance, using --debug for interactive inspection, and --skip-script-cleanup to retain generated wrapper scripts.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title accurately summarizes the main change: adding a documentation guide on debugging workflows.
Description check ✅ Passed The description covers the main changes and references the linked issue #4013, though the AI-assistance disclosure section is incomplete.
Linked Issues check ✅ Passed The PR fully addresses issue #4013 objectives: it provides a debugging guide for workflow developers and users, documents debugging tools (snakemake --debug, VS Code), log file locations, and other workflow-specific debugging guidance.
Out of Scope Changes check ✅ Passed All changes are in scope: documentation-only additions to support the debugging guide objective, with one index file update and one new guide file.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/how-to-guide-for-debugging

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

  • Generate code and open pull requests
  • Plan features and break down work
  • Investigate incidents and troubleshoot customer tickets together
  • Automate recurring tasks and respond to alerts with triggers
  • Summarize progress and report instantly

Built for teams:

  • Shared memory across your entire org—no repeating context
  • Per-thread sandboxes to safely plan and execute work
  • Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

<!--Add a description of your PR here-->
Added section on preserving wrapper scripts

### QC
<!-- Make sure that you can tick the boxes below. -->

* [ ] The PR contains a test case for the changes or the changes are
already covered by an existing test case. **Docs only**
* [x] The documentation (`docs/`) is updated to reflect the changes or
this is not necessary (e.g. if the change does neither modify the
language nor the behavior or functionalities of Snakemake).
@mrmattuschka mrmattuschka marked this pull request as ready for review March 13, 2026 11:27

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 77: Docs have small typos: remove the duplicated word "with" in the
sentence containing "Visual Studio Code <https://code.visualstudio.com/> editor
comes with with", remove the extra period in the phrase "variables.." (make it
"variables."), and replace the incorrect "library() s" token with "library()" or
"library() calls" for correct wording; update those three occurrences (the
fragments "with with", "variables..", and "library() s") accordingly in the
documentation.
- Around line 100-111: The VS Code launch snippet incorrectly sets "program":
"-m" and passes "snakemake" in the "args" list; update the launch configuration
to use "module": "snakemake" (remove the "program" entry) and remove "snakemake"
from the "args" array so the Snakemake module is launched via the "module"
field; ensure other args like "--debug", "--cores", "--nolock", "--forceall",
and "--executor" remain in "args" and keep "python":
"${command:python.interpreterPath}" as-is.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd277526-3cb0-4990-a784-f96bc2cd0cc8

📥 Commits

Reviewing files that changed from the base of the PR and between e7bcd63 and 0214ba5.

📒 Files selected for processing (2)
  • docs/index.rst
  • docs/snakefiles/debugging_workflows.rst

Comment thread docs/snakefiles/debugging_workflows.rst Outdated
Comment thread docs/snakefiles/debugging_workflows.rst

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

♻️ Duplicate comments (1)
docs/snakefiles/debugging_workflows.rst (1)

150-150: ⚠️ Potential issue | 🟡 Minor

Fix awkward phrasing: "library() s".

The phrasing "library() s" is awkward. Consider rephrasing to one of:

  • "load all the libraries you need"
  • "load all the library() calls you need"
  • "call all the library() functions you need"
📝 Suggested fix
-Start an interactive R session and load all the ``library()`` s that you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:
+Start an interactive R session and load all the libraries you need for the script. Then you can load the full workspace and interactively explore / debug what's going on:
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/snakefiles/debugging_workflows.rst` at line 150, The sentence "load all
the ``library()`` s that you need" uses awkward spacing and pluralization;
update the wording in docs/snakefiles/debugging_workflows.rst to a clearer
phrase such as "load all the libraries you need", "call all the `library()`
functions you need", or "load all the `library()` calls you need" and ensure the
inline code formatting remains for `library()` where appropriate (reference
symbol: library()).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 150: The sentence "load all the ``library()`` s that you need" uses
awkward spacing and pluralization; update the wording in
docs/snakefiles/debugging_workflows.rst to a clearer phrase such as "load all
the libraries you need", "call all the `library()` functions you need", or "load
all the `library()` calls you need" and ensure the inline code formatting
remains for `library()` where appropriate (reference symbol: library()).

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 520eef59-a74f-4692-959c-2ff796e0b822

📥 Commits

Reviewing files that changed from the base of the PR and between 8f4af4e and b19f93c.

📒 Files selected for processing (2)
  • docs/index.rst
  • docs/snakefiles/debugging_workflows.rst
🚧 Files skipped from review as they are similar to previous changes (1)
  • docs/index.rst

@mrmattuschka mrmattuschka changed the title docs: Added guide on debugging workflows (#4028) docs: Added guide on debugging workflows Mar 17, 2026

@dlaehnemann dlaehnemann 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.

This looks good, thanks for taking the time to bring this together. I mostly have some minor suggestions, and on thing that will especially make further reviewing and editing easier:

We generally try to have one sentence per line. That way the diffs are easier to read.

But only apply that once you've gone through the suggestions, as they might otherwise not be rendered correctly any more...

Comment thread docs/snakefiles/debugging_workflows.rst Outdated
Comment thread docs/snakefiles/debugging_workflows.rst Outdated
Comment thread docs/snakefiles/debugging_workflows.rst Outdated
Comment thread docs/snakefiles/debugging_workflows.rst Outdated
Co-authored-by: David Laehnemann <1379875+dlaehnemann@users.noreply.github.com>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/snakefiles/debugging_workflows.rst`:
- Line 21: Replace the misspelled word "pluging" with "plugin" in the sentence
containing "documentation of the respective executor pluging" so the text reads
"documentation of the respective executor plugin"; update the sentence in
docs/snakefiles/debugging_workflows.rst (the line containing that phrase) to fix
the typo and resolve the Codespell failure.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5a2e23b8-7794-408d-a012-0e68a232511d

📥 Commits

Reviewing files that changed from the base of the PR and between 16ade14 and 42c54e5.

📒 Files selected for processing (1)
  • docs/snakefiles/debugging_workflows.rst

Comment thread docs/snakefiles/debugging_workflows.rst Outdated
@mrmattuschka mrmattuschka requested a review from dlaehnemann April 1, 2026 14:53
@mrmattuschka

Copy link
Copy Markdown
Contributor Author

Hi @dlaehnemann , thanks for the suggestions, included them.

We generally try to have one sentence per line. That way the diffs are easier to read.

Done!

Added a (really minimal) example on the breakpoints as well.

@m-jahn

m-jahn commented Apr 16, 2026

Copy link
Copy Markdown
Member

@dlaehnemann @mrmattuschka All points have been addressed, so this is ready to be merged?

@johanneskoester johanneskoester merged commit 3d052ae into main May 22, 2026
52 of 59 checks passed
@johanneskoester johanneskoester deleted the docs/how-to-guide-for-debugging branch May 22, 2026 08:42
johanneskoester pushed a commit that referenced this pull request May 29, 2026
🤖 I have created a release *beep* *boop*
---


##
[9.21.1](v9.21.0...v9.21.1)
(2026-05-29)


### Bug Fixes

* add default json function to benchmarks
([#4128](#4128))
([41fab22](41fab22))
* do not rerun when checkpoint job missing but downstream file exists
([#4124](#4124))
([a060b93](a060b93))
* ensure that error logs contain all available details
([#4183](#4183))
([74a86e9](74a86e9))
* handle missing pss attribute in benchmark on Windows
([#4160](#4160))
([da52080](da52080))
* implement Resources.setdefault
([#3968](#3968))
([2413e99](2413e99))
* reporting remote nodes number
([#3978](#3978))
([8c534f0](8c534f0))
* resolve pathvars before constructing storage queries
([#3969](#3969))
([bd15237](bd15237))
* storage temp() file cleanup with RemoteProvider
([#4189](#4189))
([898bad1](898bad1))
* tolerate FileNotFoundError in drop_iocache
([#4153](#4153))
([#4191](#4191))
([ce26b28](ce26b28))


### Documentation

* Added guide on debugging workflows
([#4029](#4029))
([3d052ae](3d052ae))
* **cli:** Remove broken ref bold markup
([#4204](#4204))
([1200ebf](1200ebf))
* remove duplicated resources attribute in rules.rst
([#4190](#4190))
([6c8ecdd](6c8ecdd))
* **rules:** Update script type hint advice
([#4193](#4193))
([6108712](6108712))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: How-to guide for debugging

4 participants