Workflow Debugging Guide
Status: โ
Implemented (v0.2.0)
Module: yanshi-cli::commands::workflow::debug
Overview
Yanshi provides comprehensive debugging tools to help you inspect, analyze, and validate workflows before execution. The workflow debug command offers multiple inspection modes to understand workflow structure, dependencies, and execution plans.
Features
- ๐ณ DAG Visualization: Text-based visualization of workflow graph
- โ Validation: Detect configuration errors and potential issues
- ๐ Analysis: Workflow metrics and complexity analysis
- ๐ Execution Planning: See how workflows will execute
- ๐งช Dry Run: Simulate workflow execution without running nodes
- ๐ Bottleneck Detection: Identify potential performance issues
Quick Start
# Show all debug information
yanshi workflow debug my_workflow.yml
# Specific analysis modes
yanshi workflow debug my_workflow.yml --visualize
yanshi workflow debug my_workflow.yml --validate
yanshi workflow debug my_workflow.yml --analyze
yanshi workflow debug my_workflow.yml --plan
yanshi workflow debug my_workflow.yml --dry-run
# Combine flags
yanshi workflow debug my_workflow.yml --visualize --plan --verbose
Command Reference
Basic Usage
yanshi workflow debug <workflow_file> [FLAGS]
Flags
| Flag | Description |
|---|---|
--visualize | Visualize the workflow DAG structure |
--validate | Validate workflow configuration |
--analyze | Analyze workflow metrics and complexity |
--plan | Show execution plan with parallelism |
--dry-run | Simulate workflow execution |
-v, --verbose | Enable detailed output |
Note: If no flags are specified, all modes except --dry-run are shown.
Debugging Modes
1. Workflow Validation
Validates workflow configuration and detects common issues:
yanshi workflow debug my_workflow.yml --validate
Checks for:
- Empty workflows (no nodes defined)
- Duplicate node IDs
- Invalid dependencies (non-existent nodes)
- Circular dependencies
- Unreachable nodes (warnings)
- Node type distribution
Example Output:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ WORKFLOW VALIDATION
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Workflow: AI Research Assistant
Total nodes: 6
โ
No validation issues found
Node types summary:
- llm: 3
- while: 1
- template: 1
- markmap: 1
2. DAG Visualization
Displays workflow structure as a text-based tree:
yanshi workflow debug my_workflow.yml --visualize
Shows:
- Node hierarchy and dependencies
- Node types
- Parameter counts (with
--verbose) - Dependency relationships
Example Output:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ณ WORKFLOW VISUALIZATION
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Workflow: AI Research Assistant
โโ [while] search_loop
โโ 6 parameter(s)
โโ [llm] summarize_paper
โโ 2 parameter(s)
โโ [llm] detect_language
โโ 1 parameter(s)
โโ [template] final_summary_selector
โโ 1 parameter(s)
Dependencies:
summarize_paper โ ["search_loop"]
detect_language โ ["summarize_paper"]
final_summary_selector โ ["summarize_paper"]
3. Workflow Analysis
Analyzes workflow complexity and structure:
yanshi workflow debug my_workflow.yml --analyze
Metrics Provided:
- Total nodes count
- Dependency statistics (total, average, maximum)
- Workflow depth (execution levels)
- Bottleneck detection (nodes with many dependents)
- Parallelism opportunities
- Node type distribution
Example Output:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ WORKFLOW ANALYSIS
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Workflow Metrics:
Total nodes: 6
Total dependencies: 5
Average dependencies per node: 0.8
Max dependencies on single node: 1
Workflow depth: 4 levels
Max dependents: 2
Node Type Distribution:
- llm : 3 ( 50.0%)
- while : 1 ( 16.7%)
- template : 1 ( 16.7%)
- markmap : 1 ( 16.7%)
Bottleneck Detection:
โ ๏ธ Potential bottlenecks (nodes with many dependents):
- 'data_fetch': 5 nodes depend on it
- 'preprocessing': 4 nodes depend on it
4. Execution Plan
Shows how the workflow will execute with parallelism information:
yanshi workflow debug my_workflow.yml --plan
Shows:
- Execution levels (stages)
- Parallel execution opportunities
- Node dependencies (with
--verbose) - Maximum parallelism factor
Example Output:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐
EXECUTION PLAN
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Estimated Execution Plan:
(Nodes at the same level can execute in parallel)
Level 0 (1 node):
โโ [while] search_loop - (no dependencies)
Level 1 (1 node):
โโ [llm] summarize_paper - depends on: ["search_loop"]
Level 2 (2 nodes):
โโ [llm] detect_language - depends on: ["summarize_paper"]
โโ [template] final_summary_selector - depends on: ["summarize_paper"]
Level 3 (2 nodes):
โโ [llm] translate_summary - depends on: ["detect_language"]
โโ [markmap] create_mindmap - depends on: ["final_summary_selector"]
Total execution levels: 4
Maximum parallelism: 2
5. Dry Run
Simulates workflow execution without actually running nodes:
yanshi workflow debug my_workflow.yml --dry-run
Shows:
- Step-by-step execution simulation
- Node execution order
- Dependencies at each step
- Parameter configuration status
Example Output:
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐งช DRY RUN
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Simulating workflow execution: AI Research Assistant
๐ Level 0 - Executing 1 node(s)
โถ๏ธ Node: search_loop
Type: while
Parameters: 6 configured
โ Simulation passed
๐ Level 1 - Executing 1 node(s)
โถ๏ธ Node: summarize_paper
Type: llm
Dependencies: ["search_loop"]
Parameters: 2 configured
โ Simulation passed
...
โ
Dry run completed successfully
Total levels: 4
Total nodes: 6
Use Cases
1. Pre-flight Validation
Before running a complex workflow, validate its configuration:
yanshi workflow debug production_pipeline.yml --validate
This catches:
- Typos in node IDs
- Missing dependencies
- Circular dependency loops
- Configuration errors
2. Optimize Parallelism
Analyze workflow to maximize parallel execution:
yanshi workflow debug data_pipeline.yml --analyze --plan
Look for:
- Nodes at the same level (can run in parallel)
- Bottlenecks (high dependent count)
- Opportunities to restructure for better parallelism
3. Understand Complex Workflows
Visualize large or unfamiliar workflows:
yanshi workflow debug complex_workflow.yml --visualize --verbose
Quickly understand:
- Overall workflow structure
- Node relationships
- Execution flow
4. Debug Workflow Issues
When a workflow fails or behaves unexpectedly:
yanshi workflow debug failing_workflow.yml --analyze --dry-run --verbose
Identify:
- Unreachable nodes
- Unexpected dependencies
- Configuration problems
Common Patterns
Quick Health Check
# Validate and show structure
yanshi workflow debug workflow.yml --validate --visualize
Performance Analysis
# Analyze parallelism and bottlenecks
yanshi workflow debug workflow.yml --analyze --plan --verbose
Pre-production Verification
# Comprehensive check before deployment
yanshi workflow debug workflow.yml
Development Workflow
# Quick validation during development
yanshi workflow debug workflow.yml --validate --plan
Validation Error Examples
Circular Dependency
โ Issues found: 1
1. Circular dependency detected: node_a -> node_b -> node_a
Solution: Remove the circular dependency by restructuring the workflow.
Missing Dependency
โ Issues found: 1
1. Node 'process_data' depends on non-existent node 'fetch_dat'
Solution: Fix the typo in the dependency reference (fetch_dat โ fetch_data).
Unreachable Node
โ ๏ธ Warnings: 1
1. Node 'cleanup' may be unreachable
Solution: Ensure the node has dependencies or is a root node.
Best Practices
1. Validate Before Running
Always validate workflows before execution:
yanshi workflow debug workflow.yml --validate
2. Use Verbose Mode for Details
When debugging issues, use verbose mode:
yanshi workflow debug workflow.yml --verbose
3. Optimize for Parallelism
Review execution plans to identify parallelism opportunities:
yanshi workflow debug workflow.yml --plan --analyze
Look for bottlenecks and restructure if needed.
4. Monitor Complexity
For large workflows, check complexity metrics:
yanshi workflow debug large_workflow.yml --analyze
Consider splitting if:
- Depth > 10 levels
- Max dependents > 5
- Total nodes > 50
5. Document Workflow Structure
Generate visualizations for documentation:
yanshi workflow debug workflow.yml --visualize > docs/workflow_structure.txt
Integration with CI/CD
Validation in CI Pipeline
# .github/workflows/validate.yml
name: Validate Workflows
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Install Yanshi
run: cargo install yanshi-cli
- name: Validate Workflows
run: |
for workflow in workflows/*.yml; do
yanshi workflow debug "$workflow" --validate
done
Pre-commit Hook
#!/bin/bash
# .git/hooks/pre-commit
for workflow in workflows/*.yml; do
if ! yanshi workflow debug "$workflow" --validate > /dev/null 2>&1; then
echo "โ Workflow validation failed: $workflow"
exit 1
fi
done
Troubleshooting
Empty Output
If no output is shown:
- Check that the workflow file exists
- Verify the YAML is valid
- Ensure the file follows the V2 format
Validation Errors Not Clear
Use verbose mode for more details:
yanshi workflow debug workflow.yml --validate --verbose
Performance Issues
For very large workflows (>100 nodes), consider:
- Splitting into smaller sub-workflows
- Using
--validateonly (faster than full analysis) - Restructuring to reduce complexity
API for Programmatic Use
The debug functionality can also be used programmatically:
#![allow(unused)]
fn main() {
use yanshi_cli::commands::workflow::debug;
// Debug a workflow
debug::execute(
"workflow.yml".to_string(),
true, // visualize
false, // dry_run
true, // analyze
true, // validate
true, // plan
false, // verbose
).await?;
}
Future Enhancements
Planned improvements:
- ๐ Performance profiling integration
- ๐ฏ Interactive mode with node selection
- ๐ Export to Graphviz/Mermaid formats
- ๐ Advanced dependency analysis
- ๐ Automated optimization suggestions
Related Documentation
Last Updated: 2025-10-26 Version: 0.2.0