# Pattern Matcher Observability
## Summary
This RFC proposes adding opt-in debugging and observability features to the TorchInductor Patter Matcher. These features will help developers understand which patterns are applied, track per-pattern statistics and debug pattern matching issues during torch.compile() all without changing default behavior.
## Problem Statement
The Pattern Matcher is a critical optimization component in TorchInductor that performs graph transformations via search/replace patterns. Despite its importance, developers have limited visibility into its operation.
### Current capabilities
| Capability | Current State |
|------------|---------------|
| Debug pattern matching | Available via TORCHINDUCTOR_PATTERN_MATCH_DEBUG=<node_name> |
| See failure reasons | Available (using env var above) |
| Track pattern counts | Aggregate only |
| Debug multiple nodes | Not available |
| Log all applied patterns | Not available |
| Per pattern counts | Not available |
### Current Limitations
- **Single node only**
- Must specify exact node name; cannot debug multiple nodes or all nodes
- **Must know node name in advance**
- Requires dumping graph first to find node names
- **No summary view**
- No aggregate statistics showing which patterns applied or failed
- **No documentation**
- Users must discover these features by reading source code
## Benefits
- **Compiler developers**: Identify slow patterns or patterns that frequently fail matching
- **Model developers**: Understand which optimizations torch.compile() applies to their model
- **Pattern authors**: Verify new patterns are correctly applied during development
## Proposed Features
### Feature 1: Enhanced Debug Mode
Extend TORCHINDUCTOR_PATTERN_MATCH_DEBUG to support multiple nodes.
**Current Behavior:**
- TORCHINDUCTOR_PATTERN_MATCH_DEBUG=add → debugs only node named exactly “add”
**Proposed Behavior:**
- TORCHINDUCTOR_PATTERN_MATCH_DEBUG=add → same as before (backward compatible)
- TORCHINDUCTOR_PATTERN_MATCH_DEBUG=add,mul,mm → debug multiple nodes
- TORCHINDUCTOR_PATTERN_MATCH_DEBUG=all → debug all nodes
### Feature 2: Per-Pattern Type Tracking
Track how many times each specific pattern type is applied, not just aggregate totals.
**Current Output (aggregate only)**
## Backward Compatibility
| Aspect | Status |
|--------|--------|
| Default behavior | Unchanged |
| Existing env vars | TORCHINDUCTOR_PATTERN_MATCH_DEBUG= works exactly as before |
| Existing failure messages | Preserved format unchanged |
| Public APIs | No breaking changes |
## Proposed Environment Variables
| Variable | Purpose | Values |
|----------|---------|--------|
| TORCHINDUCTOR_PATTERN_MATCH_DEBUG | Debug specific nodes (existing) | <node_name>, ,, all |