2
Oct
2011

How to Debug Drupal and LAMP

Atlanta Drupal Users Group logo Using a more scientific method & customer-centric approach to debugging Drupal, rather than randomly trying things, will greatly increase your productivity.

This presentation was given by Robert Ristroph at DrupalCamp Atlanta 2011.

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.

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:

  1. Gather initial info
    1. from customers
    2. Learn location of all logs, look at lesser known (mysql); watchdog/syslog (logs, screenshots).
  2. Make an EASY-to-Test hypothesis (may narrow down where problem is located: Divide & conquer)
  3. Test it, Analyze it
  4. Refine hypothesis & go back to Step 2

Customers

  • 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)

  1. Clear all caches (browser, drupal, varnish, etc)
  2. Do you have the right version of code is on server?
  3. Change to garland (eliminate custom theme as problem)
  4. Check for old css/js being delivered from a CDN
  5. Remember your own dumb mistakes & check (i.e. is it plugged in?)
  6. 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

Common Bugs

List-checking for cheap and common bugs can't replace THINKING!

  1. Permissions on input filter
  2. Rebuild node_access table
  3. Permissions on imagecache and aggregated js/css files (whole /files)
  4. Content Permissions is giving access to some CCK fields and not others
  5. Cron related (cron_semaphore)
  6. Keep your own list (perhaps per project)

Inspection Tips (General)

Goal: to see behind the curtain/inside the system

  1. krumo/devel module
  2. PRIMITIVE print method (print out indiv variables for checking, can't do with giant objects)

      print("<pre>".$stuff."</pre>"); 
      print("<pre>".print_r($stuff,TRUE)."</pre>");

  3. use watchdog() for values on pages that refresh or are in a cron hook
  4. 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
  5. 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)

  1. ALWAYS keep a copy of the database in original state, do experiments, compare (diff), and then RESTORE to original state.
  2. Having an original/starting point database copy can be key to replicating problems
  3. Use drush to dump variables to files, then diff (compare)
  4. Try not to end up blindly scanning the differences; develop hypothesis/guess/theory and look for that specifically

Devel Module

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

  1. devel module themer module
  2. limits on number of CSS files - IE especially [make sure CSS aggregation is on]
  3. hook_form_alter() vs. hook_form_FORMID_alter() and module weights
  4. typography and even color profiles in images are handled differently in different browsers/platforms
  5. Firebug plugin for Firefox

Performance Debugging Tips

  1. learn how to use "ab" (apache bench)
  2. wget (-r) spiders
  3. mysql logs & innotop [like printing out variables]
  4. cool trick: put a header indicating a cache hit or miss, that you can look for with the LiveHTTPHeaders Firefox installation
  5. 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

  1. Module weights, order of hook operations [systematically disable modules]
  2. Theme/Module interaction
  3. External service requests
  4. Mis-use of APIs