Keyboard shortcuts

Press โ† or โ†’ to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

FlagDescription
--visualizeVisualize the workflow DAG structure
--validateValidate workflow configuration
--analyzeAnalyze workflow metrics and complexity
--planShow execution plan with parallelism
--dry-runSimulate workflow execution
-v, --verboseEnable 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:

  1. Check that the workflow file exists
  2. Verify the YAML is valid
  3. 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 --validate only (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

Last Updated: 2025-10-26 Version: 0.2.0