Debugging (Drupal)

Following are notes from a dashed off presentation on debugging. There's a bit of a Drupal slant here.

On Successful Debugging

  1. Define the problem
    1. Gathering information in order to define the problem is the first step towards resolving it. You’ll be tempted to jump on the first likely explanation in your hurry to resolve the problem. Feel free to test those, but if they don’t quickly become promising, return to this step. Being over-anxious to solve an issue narrows one’s mental focus, and that is harmful during this phase. Be thorough. Go slow to go fast.
    2. What are the steps to reproduce the problem?
    3. Obtain specific info from the reporter.
      1. Only happens on certain URLs?
      2. ...Browsers?
      3. ...Clickpaths?
      4. ...Specific functionality or UI features?
      5. ...Certain users/roles?
      6. Reproducible in all environments?
    4. Is there only one problem, or are there multiple problems we need to decouple?
    5. Are there existing bug reports that may be related/the same problem
    6. Any recent updates to code or configurations that may have caused it? Talk to other developers.
    7. Does clearing the cache or restarting the servers help?
    8. Is the problem appear to be a frontend or backend problem? Or a networking issue? Or a server config issue?
    9. Search for others experiencing this issue. Searches might include error message output, or descriptions of the behavior and modules or themes suspected of being involved.
    10. Talk to other developers.
    11. Submit an issue on
  2. Isolate the problem
    1. Frontend
      1. Use browser developer toolbar JS console.
        1. Trigger the bug and look for JS errors in the console log.
        2. Is there broken JS causing scripts to fail to execute?
        3. Is there malfunctioning JS?
        4. Debug JS using console.log() to write introspections to the JS console log.
        5. Test Drupal jQuery in the JS console like this:(function ($) {  $('h1').hide();  console.log('Give me back me Lucky Charms!');}(jQuery));
    2. Backend
      1. Check the Drupal dblog or syslog if either are enabled in the site.
      2. Check the  PHP error logs. If you don’t know where they’re at, check the phpinfo() output in the Drupal status report, or via a script you add to the site.
      3. Is the issue related to caching?
      4. Is the problem related to user roles/permissions?
      5. Are there broken services or integrations that could explain the problem?
      6. Debug PHP using dpm() to write output to the screen.
      7. Test code using the Devel PHP evaluation tool at /devel/php.
        1. Call functions to verify they return the right info.
        2. Look into the database when you don’t have access.
      8. debug_backtrace(), get_defined_vars().
      9. Debug PHP using error_log(var_export($data_to_introspect, 1)) to write output to the PHP error logs, a helpful approach when you can’t display to the screen - e.g. testing a web service call being made.
      10. Debug with xDebug. Set breakpoints. Step through code.
        1. Get xDebug:
        2. Use it with PhpStorm IDE:
          2. Video Tutorial:
    3. HTTP, Networking and Cookies
      1. Redirect Path Chrome Plugin (
      2. EditThisCookie Chrome Plugin (
      3. HTTP Headers Plugin (
      4. GA Debugger Chrome Plugin (
      5. Developer Toolbar Plugin (
      6. Built in Developer Tool
        1. Network Tab
    4. Database and Internals
      1. devel/php
      2. shell_exec() - for READ actions only.
    5. Performance
      1. YSlow Plugin (
      2. SpeedTracer Plugin (
      3. NewRelic
      4. *CacheGrind (to analyze logs created by xDebug) for Profiling
    6. Services
      1. Test with curl, or one of the browser plugins for testing services, or with PHP or Python (etc.) testing rigs.
  3. Solve the problem
    1. Test fixes individually first so you know exactly the change that solves the issue.
    2. Sometimes problems result as a compound of circumstances (e.g. a Javascript error that only shows up in IE8, and then only in one environment when configured in manner X while multiple web heads are in play). These can be a challenge. Methodical debugging will help you solve parts of the problem, and eventually assemble a multi-part solution. Again, the goal is to isolate the problem(s), and each part is an individual problem, even if they all only result in one symptom.
    3. If you located patches, test them. If the patch is incomplete or out of date, can  you improve it?
    4. Test fixes you make to code.
      1. If it works - is this something we can submit back to as a patch?
    5. Run through steps to reproduce the issue. Is it resolved? Are there additional cases that may need to be accounted for?
    6. Submit the fix for QA.
    7. Alternatively, are there constraints (time, scope, risk, etc.) that may call for a “punt” solution, or a workaround to “solve” the problem?
      1. Work up a justification for suggesting the workaround and attach it to your ticket.
      2. Communicate with supervisors and clients so a consensus can be reached regarding the solution route.
      3. On the problem’s ticket, document on the “right” way to solve it, when constraints allow.

Find Me Around

User login