How to Debug Drupal and LAMP
Equally importantly, Rob gives specific tips and tools for debugging common problems in the different parts of a Drupal installation.
If my notes in this post are not enough, you can also watch a video of Rob's similar presentation in June at the Colorado DrupalCamp.
- General Tips
- Drupal Tips
For further reading, Rob highly recommends http://www.debuggingrules.com (David Agans)
Why Debugging is important
- You'll spend more of your life is debugging than coding (Maurice Wilkes quote)
- Debugging=a PROCESS that increases productivity
- Debugging=developing an understanding of a coding error, so that the behavior of the code and your expectations of it match.
- Bug=mismatch between programmer's (YOUR) mental model of what code should do & what it does. You gave wrong instructions.
- This reinforces the Erik Webb's emphasis in "Thinking like a Drupal Developer" that one must THINK through architecture & function before coding!
Scientific Method Approach
Since a bug is a model vs reality mismatch, think of your model as a hypothesis that needs tested. The scientific method gives a great way to structure your debugging! Steps in scientific method include: Hypothesize, Test, Refine & Repeat. For debugging in Drupal that looks like:
- Gather initial info
- from customers
- Learn location of all logs, look at lesser known (mysql); watchdog/syslog (logs, screenshots).
- Make an EASY-to-Test hypothesis (may narrow down where problem is located: Divide & conquer)
- Test it, Analyze it
- Refine hypothesis & go back to Step 2
- Valuable debugging info comes from CUSTOMERS, so teach users how to do good bug reports & take screen shots.
- Because you can't DeBug unless you can replicate the bug; the relationship with users/customers is key.
Cheap Tests (try first)
- Clear all caches (browser, drupal, varnish, etc)
- Do you have the right version of code is on server?
- Change to garland (eliminate custom theme as problem)
- Check for old css/js being delivered from a CDN
- Remember your own dumb mistakes & check (i.e. is it plugged in?)
- Did someone else already solve it?
- Search for the EXACT error message (except for node numbers, domain name, etc.)
- ask on #drupal-support
- Try dev version of modules (be sure can undo)
- Always post to describe your issue & to confirm when/how fixed
List-checking for cheap and common bugs can't replace THINKING!
- Permissions on input filter
- Rebuild node_access table
- Permissions on imagecache and aggregated js/css files (whole /files)
- Content Permissions is giving access to some CCK fields and not others
- Cron related (cron_semaphore)
- Keep your own list (perhaps per project)
Inspection Tips (General)
Goal: to see behind the curtain/inside the system
- krumo/devel module
- PRIMITIVE print method (print out indiv variables for checking, can't do with giant
- use watchdog() for values on pages that refresh or are in a cron hook
- Fancy tools (xdebug/breakpoints/code tracing)=good, but don't replace learning how to think/debug
- Comment in session: if you enable xdebug in PHP, you get better error reporting, but there are performance/security issues with doing this in production
- RECOMMENDATION: the QuickStart project, a pre-made development environment for Drupal
- Use standard debugging tools/setup in your shop, so everyone's on same page (IDE ideas: vi or emacs, then use tool with xdebug integrated when needed, others use eclipse or netbeans)
Inspection Tips (Database)
- ALWAYS keep a copy of the database in original state, do experiments, compare (diff), and then RESTORE to original state.
- Having an original/starting point database copy can be key to replicating problems
- Use drush to dump variables to files, then diff (compare)
- Try not to end up blindly scanning the differences; develop hypothesis/guess/theory and look for that specifically
yoursite.com/devel/php as a way to do quick tests - check if a
PHP extension is installed; or
unserialize a cut-and-paste from the db; test code snippets for expected behavior [beware security risk]
1. node access/ permissions block for debugging
2. user switcher for recreating problems (have a test user for every role)
3. look at query list
4. devel features are a kind of "common problems" list
Theme Debugging Tips
- devel module themer module
- limits on number of CSS files - IE especially [make sure CSS aggregation is on]
- hook_form_alter() vs. hook_form_FORMID_alter() and module weights
- typography and even color profiles in images are handled differently in different browsers/platforms
- Firebug plugin for Firefox
Performance Debugging Tips
- learn how to use "ab" (apache bench)
- wget (-r) spiders
- mysql logs & innotop [like printing out variables]
- cool trick: put a header indicating a cache hit or miss, that you can look for with the LiveHTTPHeaders Firefox installation
- Use of xhprof & similar needs to be targeted at a problem
Interaction Debugging Tips
Are hardest to diagnose, they resist compartmentalization (divide/conquer), because they involve 2 bug-free components interacting
- Module weights, order of hook operations [systematically disable modules]
- Theme/Module interaction
- External service requests
- Mis-use of APIs