Forensic Drupal DebuggingForensic Drupal Debugging

Dan HarrisDan Harrisdharris1@stanford.edudharris1@stanford.edudaneesia on drupal.orgdaneesia on drupal.org

AgendaAgenda

Basic Principles: what are the cluesBasic Principles: what are the clues Drupal UI ConfigurationDrupal UI Configuration White Screen of Death (WSOD)White Screen of Death (WSOD) Debugging with Themer/DevelDebugging with Themer/Devel Q&A SessionQ&A Session

What’s NOT CoveredWhat’s NOT Covered

Javascript bugsJavascript bugs HTML/CSS bugsHTML/CSS bugs Using a tool with breakpoints to step Using a tool with breakpoints to step

through code executionthrough code execution Performance debuggingPerformance debugging Anything not mentioned on the Anything not mentioned on the

previous slideprevious slide

Reviewing Trace EvidenceReviewing Trace Evidence

Some or all of the following are part of rendering a Drupal Some or all of the following are part of rendering a Drupal page:page:– Drupal core, contributed, and custom modules/templatesDrupal core, contributed, and custom modules/templates

– HTML, CSS, and JavascriptHTML, CSS, and Javascript

– PHP, Apache, some dB software, and the host OSPHP, Apache, some dB software, and the host OS

– The browser and client OSThe browser and client OS

– Host hardware and client hardwareHost hardware and client hardware

– Load balancers, external caching, networking equipment and protocols, Load balancers, external caching, networking equipment and protocols, etc. etc.etc. etc.

All of them have versions All of them have versions All of them are possible culprits when something goes awry.All of them are possible culprits when something goes awry.

Reviewing Trace EvidenceReviewing Trace Evidence

When something goes wrong, where do I look for When something goes wrong, where do I look for clues?clues?– Output is wrong or missing, check Output is wrong or missing, check

Input filter settingInput filter setting Template and CSS files: remember that files outside you’re theme Template and CSS files: remember that files outside you’re theme

have influencehave influence Permissions and configuration settingsPermissions and configuration settings Use code to help you figure it outUse code to help you figure it out

– Error message: Error message: Check log files (Drupal, PHP, dB)Check log files (Drupal, PHP, dB) Search the message on Drupal.orgSearch the message on Drupal.org

– WSOD: in a few slidesWSOD: in a few slides

Drupal 6 UI ConfigurationDrupal 6 UI Configuration

/admin/settings/error-reporting/admin/settings/error-reporting– Staging site: write errors to log and Staging site: write errors to log and

screen; screen;

– Production: write errors to the log onlyProduction: write errors to the log only

Drupal 6 UI ConfigurationDrupal 6 UI Configuration

/admin/settings/performance/admin/settings/performance– Disable all caching/compression on staging (no Disable all caching/compression on staging (no

need)need)– May selectively disable these when debugging on May selectively disable these when debugging on

productionproduction Remember to flush caches whenRemember to flush caches when

– Introducing a new module/theme fileIntroducing a new module/theme file– If you have caching enabled and change something If you have caching enabled and change something

like a menulike a menu

Drupal 6 UI ConfigurationDrupal 6 UI Configuration

/admin/settings/admin/admin/settings/admin– Consider using a separate theme for adminConsider using a separate theme for admin

– I like Adaptivetheme for this purposeI like Adaptivetheme for this purpose

Some useful code if you use an admin module:Some useful code if you use an admin module:function YOURMODULE_init() {function YOURMODULE_init() {

if ( (arg(0) == 'node' && arg(1) == 'add') || if ( (arg(0) == 'node' && arg(1) == 'add') ||

(arg(0) == 'node' && arg(2) == 'edit') || (arg(0) == 'node' && arg(2) == 'edit') ||

… …) )

{{

if ($admin_theme = variable_get('admin_theme', 0)) {if ($admin_theme = variable_get('admin_theme', 0)) {

global $custom_theme;global $custom_theme;

$custom_theme = $admin_theme;$custom_theme = $admin_theme;

drupal_add_css(); // Use to add custom CSS for your admin themedrupal_add_css(); // Use to add custom CSS for your admin theme

} }

}}

}}

Drupal Status Report and LogsDrupal Status Report and Logs

/admin/reports/status & /admin/reports/status & /admin/reports/dblog/admin/reports/dblog

Check these often, especially whenCheck these often, especially when– Site in developmentSite in development

– First couple weeks after deploymentFirst couple weeks after deployment

Gotcha when Using the Gotcha when Using the Collaboration ToolsCollaboration Tools Updating Drupal normally 2 stepsUpdating Drupal normally 2 steps

– 1) Update modules; 2)Run update.php1) Update modules; 2)Run update.php It’s 3 steps for the Collab ToolsIt’s 3 steps for the Collab Tools

– Run collab tool updaterRun collab tool updater

– Update modules not updated by collab toolUpdate modules not updated by collab tool

– Run update.phpRun update.php Some people forget the third step!Some people forget the third step!

Debugging the WSODDebugging the WSOD

A few things to try:A few things to try:– If you’re only getting it on a particular If you’re only getting it on a particular

screen, check the log report and filesscreen, check the log report and files

– (Temporarily) paste the following into (Temporarily) paste the following into the top of index.php (after <?php): the top of index.php (after <?php):

// Use the if for a multi-site; otherwise you just need the 3 lines// Use the if for a multi-site; otherwise you just need the 3 linesif ($_SERVER['HTTP_HOST']==='some.domain.name.here') {if ($_SERVER['HTTP_HOST']==='some.domain.name.here') {  error_reporting(E_ALL);  error_reporting(E_ALL);  ini_set('display_errors', TRUE);  ini_set('display_errors', TRUE);  ini_set('display_startup_errors', TRUE);  ini_set('display_startup_errors', TRUE);

Debugging the WSODDebugging the WSOD

A few things to try:A few things to try:– Log on to the server and access the log files:Log on to the server and access the log files:

tail /var/log/apache2/error.logtail /var/log/apache2/error.log

– Check your dB & OS logs tooCheck your dB & OS logs too

– Additional resources:Additional resources:http://drupal.org/node/158043http://drupal.org/node/482956http://drupal.org/node/31819

Debugging with ThemerDebugging with Themer

Debugging with ThemerDebugging with Themer

““Firebug for Drupal Theming”Firebug for Drupal Theming” Theme hook called: indicates where and how you can hook Theme hook called: indicates where and how you can hook

into the execution.into the execution. File used: template file used to generate this part of the pageFile used: template file used to generate this part of the page

– Click the link to view the fileClick the link to view the file

Function called: click link to display API call on Function called: click link to display API call on api.drupal.orgapi.drupal.org

Preprocess functions: functions called before the section is Preprocess functions: functions called before the section is renderedrendered– A word of caution: in a sub-theme, preprocess functions targeting the A word of caution: in a sub-theme, preprocess functions targeting the

same area of execution (e.g. page) may both be run.same area of execution (e.g. page) may both be run.

Template variables provide valuable debug infoTemplate variables provide valuable debug info

A word of Caution about ThemerA word of Caution about Themer

Enabling Themer can cause other bugs!Enabling Themer can cause other bugs!– Edit Content > Manage Fields: displays Edit Content > Manage Fields: displays

field weightsfield weights

– Edit Content > Display Fields: all messed Edit Content > Display Fields: all messed upup

– Etc.Etc. Best to enable, use, then disableBest to enable, use, then disable

– The Devel block provides such capabilityThe Devel block provides such capability

Debugging with DevelDebugging with Devel

Devel can provide the following:Devel can provide the following:– dB Query informationdB Query information– Highlight slow queriesHighlight slow queries– Display page load times & memory usageDisplay page load times & memory usage– More information when PHP errors are generated More information when PHP errors are generated

via backtrace.via backtrace.– Functions to embed in your code and provide Functions to embed in your code and provide

valuable debug informationvaluable debug information– Generate content!Generate content!

Devel Function CallsDevel Function Calls dsm(), dpm(): print a variable out to an interactive UIdsm(), dpm(): print a variable out to an interactive UI

Example: Example: if (module_exists('devel')) dpm($node);if (module_exists('devel')) dpm($node); dvm(): similar to dsm/dpm except uses var_dump() instead of print_r().dvm(): similar to dsm/dpm except uses var_dump() instead of print_r(). dpr(): pretty print version of PHP print_r() calldpr(): pretty print version of PHP print_r() call

Example:Example: if (module_exists('devel')) dprint_r($_SESSION);if (module_exists('devel')) dprint_r($_SESSION);

dvr(): same as dpr, except uses var_dump().dvr(): same as dpr, except uses var_dump(). dd(): write debug information out to a filedd(): write debug information out to a file

Many many more: http://api.drupal.org/api/devel/devel.module/6Many many more: http://api.drupal.org/api/devel/devel.module/6

See also http://drupal.org/project/drupalforfirebugSee also http://drupal.org/project/drupalforfirebug

Problem Solving Best PracticesProblem Solving Best Practices

ShamelesslyShamelessly stolen from http://randyfay.com/node/40stolen from http://randyfay.com/node/40– Keep a log of changes on the site. Note when Keep a log of changes on the site. Note when

a new module is installeda new module is installed a patch is applieda patch is applied an upgrade is done. an upgrade is done. Consider using the journal module to help with this. Consider using the journal module to help with this. 

– Keep your code under source control (Git).Keep your code under source control (Git).

– Keep multiple backups of your database. Keep multiple backups of your database. Consider using the Backup and Migrate Consider using the Backup and Migrate 

– Try to have matching production, staging, and testing environmentsTry to have matching production, staging, and testing environments

– Have a quick path to replicating production to another testing Have a quick path to replicating production to another testing environmentenvironment

– Use a notebook to record changes when working through a complex Use a notebook to record changes when working through a complex debugging session.debugging session.

Where to go from HereWhere to go from Here

Join the Stanford Drupallers GroupJoin the Stanford Drupallers Group For hard-core debugging tips, view For hard-core debugging tips, view

http://www.archive.org/details/TroubleshootingInDrupalhttp://www.archive.org/details/TroubleshootingInDrupal– One tip from the video: never copy and paste code form Skype…you One tip from the video: never copy and paste code form Skype…you

have been warned have been warned – http://www.archive.org/details/DebuggingDrupal (Randy Fay)http://www.archive.org/details/DebuggingDrupal (Randy Fay)

Ask on Drupal.ogr:Ask on Drupal.ogr:– If your question is directly related to a module, place a support request If your question is directly related to a module, place a support request

in the module issue queuein the module issue queue

– If more generic, use the ForumsIf more generic, use the Forums

Q&A SessionQ&A Session

Thanks!Thanks!

Feel free to contact me:Feel free to contact me:– dharris1@stanford.edudharris1@stanford.edu

– 95slug@gmail.com95slug@gmail.com

– daneesia on Drupaldaneesia on Drupal