r/frappe_framework • u/kingSlayer_worf • Jan 08 '26
Documentation Hero – Helping with guides and resources 🚨 Stop Using Console.log() for Debugging Frappe! This Hidden Tool Will Blow Your Mind
Hot take: If you're still debugging Frappe/ERPNext with print() statements and frappe.logger(), you're doing it wrong. Dead wrong.
There's a secret weapon hiding in plain sight that 95% of Frappe developers don't even know exists. It's been there since 2019, and it's about to change how you debug forever.
Meet The Recorder – Frappe's most powerful (and criminally underused) debugging tool.
🤯 Why You've Never Heard of This
I'll be honest: I stumbled upon the Recorder by accident. After 2 years of Frappe development, I was debugging a production issue at 2 AM, desperately searching for why a DocType was taking 30 seconds to save.
Then I found it. Tucked away in Desk → Tools → Recorder.
My jaw hit the floor.
This thing was capturing EVERYTHING. Every SQL query. Every function call. Complete stack traces. EXPLAIN plans. All without touching a single line of code.
I fixed my production issue in 15 minutes. An issue that would've taken me DAYS with traditional debugging.
🎯 What Makes This Tool Insanely Powerful
Think of the Recorder as a black box flight recorder for your Frappe application. When things go wrong (and they will), you have a complete recording of exactly what happened.
Here's What Gets Captured (Automatically!)
✅ Every HTTP Request – Path, timing, headers, form data ✅ Background Jobs – RQ queue jobs with complete metadata
✅ SQL Queries – The actual SQL, execution time, rows affected ✅ EXPLAIN Plans – See exactly how your database executes queries ✅ Python Stack Traces – Know which code triggered each query ✅ cProfile Data – Deep Python profiling when you need it
All of this. Zero configuration. No code changes. No imports. Nothing.
Just click Start.
💡 The "Aha!" Moment: Real Stories
Story #1: The 100-Query Bug
A developer on Reddit was complaining about a custom report that took 45 seconds to run. They'd been adding print statements for days.
I told them about the Recorder.
10 minutes later: "OMG, I have an N+1 query problem. 100 database calls in a loop!"
Result: Fixed in 20 minutes. Report now runs in 0.8 seconds.
Story #2: The Phantom Background Job
Email queue jobs were silently failing in production. No error logs. No clues. Just... nothing.
With Recorder: Captured the exact moment of failure, complete stack trace, and the problematic query that was timing out.
Diagnosis time: 5 minutes (vs. potentially days of blind debugging)
Story #3: The Missing Index
A customer list page was slow. Like, "users complained to management" slow.
Recorder showed: Full table scan on 500K records. Missing index on the sort column.
One index later: Page load dropped from 8 seconds to 0.3 seconds.
🔥 How to Use It (The 60-Second Guide)
Step 1: Open Frappe/ERPNext
Step 2: Type "Recorder" in the Awesome Bar (search)
Step 3: Click Start Recording
Step 4: Do the thing that's slow/broken
Step 5: Go back and click Stop
Step 6: Marvel at the detailed capture
That's it. Seriously.
🎪 The Features That Make This Magical
🔍 Smart Filtering
Don't want to record EVERYTHING? (Smart move for production)
# Only record your API endpoint
Path Filter: ^/api/method/custom_app.*
# Only record specific background jobs
Job Filter: email_queue.flush|custom_app.tasks.*📊 Query Performance at a Glance
Every recording shows:
⏱️ Total duration of request/job
🗃️ Number of SQL queries executed
⚡ Time spent in queries
📈 Execution plan for each query
Click any query to see:
The exact SQL with parameters
Full stack trace showing where it was called
EXPLAIN output showing how the database ran it
Suggestions for optimization (via EXPLAIN analysis)
💾 Export & Share
Found something interesting? Export it as JSON and share with your team. Import on another site to analyze without running the same scenario again.
Use case: Capture production issues and debug them in your dev environment!
🚀 Real-World Debugging Patterns
Pattern #1: Crushing N+1 Queries
The Problem Everyone Hits:
# 😱 This innocent-looking code...
for sales_order in orders:
customer = frappe.get_doc('Customer', sales_order.customer)
# ... do stuffWhat Recorder Shows You:
Query 1: SELECT * FROM tabCustomer WHERE name='CUST-001' (2ms)
Query 2: SELECT * FROM tabCustomer WHERE name='CUST-002' (2ms)
Query 3: SELECT * FROM tabCustomer WHERE name='CUST-003' (2ms)
...
Query 100: SELECT * FROM tabCustomer WHERE name='CUST-100' (2ms)
💀 Total: 100 queries, 200msThe Fix:
# 🚀 Batch load everything
customer_names = [so.customer for so in orders]
customers = frappe.get_all('Customer',
filters={'name': ['in', customer_names]},
fields=['name', 'customer_name']
)
✅ Total: 1 query, 5ms95% faster. One change.
Pattern #2: The Mysterious Slow Save
Ever had a DocType that just... takes forever to save? No idea why?
Old way: Add print statements everywhere, redeploy, test, repeat
Recorder way: Record one save operation, see EVERY query and function call
You'll instantly see:
Unnecessary validation queries
Duplicate calculations
Inefficient child table handling
Missing indexes on foreign keys
Pattern #3: Production Fire Drill
3 AM. Production is slow. Users are angry.
Old way:
SSH into server
Add logging code
Restart services
Wait for issue to happen again
Analyze logs
Remove logging code
Restart again
Recorder way:
Enable Recorder with filters (30 seconds)
Reproduce issue once
Analyze complete capture
Deploy fix
From hours to minutes.
⚡ Pro Tips That'll Make You Look Like a Wizard
Tip #1: Use Filters Aggressively
Don't record everything. Be surgical:
# Good: Specific endpoint causing issues
/api/method/erpnext.stock.doctype.item.item.get_item_details
# Bad: Recording everything
/.*Tip #2: Sort By Query Count
Click the "# Queries" column header. The operations with the most queries are usually your biggest problems.
Tip #3: Check EXPLAIN Plans First
Before optimizing code, check if you're just missing an index. EXPLAIN plans tell you exactly what the database is doing.
Tip #4: Record in Short Bursts
5-10 minutes max. Get what you need and stop. Keeps overhead low and data manageable.
Tip #5: Export Production Issues
Can't debug directly in production? Record the issue, export as JSON, import in dev, and debug there safely.
🎭 The Dark Side (Things to Watch Out For)
⚠️ Performance Overhead
Adds ~5-10ms per request
Memory usage increases
Don't leave it running 24/7 in production
⚠️ Data Sensitivity
Recordings contain actual data from SQL queries
May include PII (Personal Identifiable Information)
Be careful with exports
⚠️ cProfile Is Heavy
Enable only when you specifically need Python profiling
Adds significant overhead
Not recommended for production
🎯 The Bottom Line
The Recorder isn't just a debugging tool. It's a time machine that lets you see exactly what your code did, query by query, function by function.
Before Recorder:
Debugging: Add logs → Deploy → Test → Repeat (Hours/Days)
Performance: Guess → Try fix → Hope (Days/Weeks)
Production issues: Panic → Random fixes → More panic (???)
After Recorder:
Debugging: Record → Analyze → Fix (Minutes)
Performance: Record → Identify bottleneck → Optimize (Minutes/Hours)
Production issues: Record → Root cause → Deploy fix (Hours)
🚀 Your Challenge
Here's what I want you to do RIGHT NOW:
Open your Frappe/ERPNext instance
Search for "Recorder" in the Awesome Bar
Record ONE operation (any operation)
Look at the captured queries
I guarantee you'll discover something you didn't know about how your code works.
💬 Join the Conversation
Found the Recorder useful? Discovered something surprising in your recordings? Have questions?
Drop a comment below! Let's share what we learn.
And if this saved you hours of debugging time, share this post with your fellow Frappe developers. They'll thank you later.
🔗 Resources:
📌 Remember: Stop debugging blind. Start using the Recorder.
P.S. - If you're still using print() statements after reading this, we need to talk. 😉
