Opening The Black Box

Trying to tame a modern, fully-featured web application like Drupal can be an exercise in frustration.

Why are you printing that piece of content there?
Why am I seeing a negative integer instead of a string from this function?
What could a PDOException in my Watchdog log possibly mean?
In this session, we will be going over useful debugging tools and techniques that can help you start to see into the inner workings of all versions of Drupal, including the new kid on the block, Drupal 8. You will be better prepared to start building truly custom features into your projects and you’ll be able to remain calm when you get the ineveitable email that your site is showing the dreaded White Screen Of Death at 4:45pm on a Friday afternoon.

Presented at:
DrupalCamp NJ 2017
Full Slidedeck with Speaker Notes:
https://github.com/milsyobtaf/prez/raw/primary/2017/DrupalCampNJ/opening-the-black-box_notes.pdf

Transcript

1. DrupalCamp NJ 2/4/2017 Opening The Black Box
2. Howdy! Dustin Younse @milsyobtaf I’m an engineer at Acquia
3. What Is Debugging?
4. Nothing But Text?
5. • CSS aggregated but not cached • JS blocked in the browser • File permissions in sites/default/files Nothing But Text?
6. • Mostly a semantic difference • 5 minutes vs 5 hours? • “Fixed” vs understood and corrected Debugging vs Troubleshooting
7. What Is The Black Box?
8. • Non-technical education • Self taught web skills • Above average Googling abilities • Late nights staring at error messages A Familiar Story?
9. What Is Drupal?
10. Mental Model of Drupal
11. Mental Model of Drupal
12. Mental Model of Drupal
13. Mental Model of Drupal
14. Mental Model of Drupal
15. Start At The Beginning
16. When All You Have Is A Hammer CC by 2.0 https://www.flickr.com/photos/raindrift/7095238893/
17. Text Editors • “Text Editors” • Text Editors • IDEs
18. • Notepad (Windows) • Text Edit (Mac) • Nano (Linux / Mac) “Text Editors”
19. • Notepad++ (Windows) • vim (Mac / Linux) • Dreamweaver (Mac / Windows) • Sublime Text (Mac / Linux / Windows) • Atom (Mac / Linux / Windows) Text Editors
20. • PHPStorm (Mac / Linux / Windows) • Eclipse (Mac / Linux / Windows) • Komodo (Mac / Linux / Windows) Integrated Development Environments
21. • emacs (Mac / Linux / Unix / Everything else) Operating Systems With Built In Text Editors
22. Development Environments • On your server • On your machine • On your machine, but it acts like the server
23. Development Environments • FTP Development • “Cowboy coding” • Local Environments • MAMP / LAMP / Vagrant • Next generation • Kalabox • DrupalVM
24. • FTP Development • “Cowboy coding” • No version control up front • Little debugging visibility • Log files (maybe), debug statements • Watchdog logs (maybe) FTP Development
25. • print_r() • Raw dump of a variable or context, no formatting • print_r($node); • <pre><?php print_r($node); ?></pre> • dsm() / kint() • Formatted dump of a variable or context • dsm($node); Debug Statements in Code
26. • MAMP / Dev Desktop / Native LAMP • Code runs entirely locally • Added bonus of offline work, no internet required • print_r(), dsm(), kint(), but also more • xdebug Local Development
27. • Kalabox with Pantheon / Acquia integration • DrupalVM and other custom Vagrant boxes • print_r(), dsm(), kint(), xdebug • Very accurate performance profiling • XHProf • Blackfire • Tidewater Local Development: The Next Generation
28. What’s xdebug?
29. • Hitting pause on code execution • Inspecting the current state of “the stack” • Modifying values live xdebug: Step Through Debugging
30. Something Is Broken!
32. Relax.
33. Remember Cobble’s Knot
34. • Is something not showing up? • New content - is it published? • Old content - are permissions set properly? • Is something showing up that shouldn’t? • Raw HTML and Javascript in a WYSIWYG field? What’s Broken?
35. • Log Files • You should learn how to find your log files 
 before you need your log files • multitail • Linux / Mac utility to easily view logs
 with more options than tail Work From The Bottom Up
36. • Custom Module • template.php / .theme file • Theme Template Where Is It Broken?
38. The Scientific Method
39. • Change one thing at a time • Test that change • Repeat Finally, Debugging
40. • Save your progress as you work • Recreate your Features or config yml • Makes rabbit holes manageable git Is Your Friend
41. • Let’s you isolate changes between commits git bisect Is Your Friend
42. git bisect Is Your Friend
43. git bisect Is Your Friend
44. • Remove your debug statements • Ensure you only changed as much as you 
 needed to change • You only commit dsm(‘Butts’); to master once git diff Is Your Friend
45. git blame Finds Your Enemies
46. git blame Finds Your Enemies
47. • Can help you track down who wrote 
 the offending code • This should not be a witch hunt • This should be a chance to find 
 context for the issue git blame Is Your Friend
48. • Can help you track down who wrote 
 the offending code • This should not be a witch hunt • This should be a chance to find 
 context for the issue git annotate Is Your Friend
49. Make The Future Easier
50. • watchdog() (D7) • \Drupal::logger() (D8) • syslog Module • https:/ /loggly.com • https:/ /www.elastic.co/blog/heya-elastic-stack-and-x-pack • https:/ /www.sumologic.com • Write a test! • Simpletest • Behat Proactive Debugging
51. • The Art of Troubleshooting by Jason Maxham • https:/ /artoftroubleshooting.com/book/ • Debugging: The 9 Indispensable Rules for 
 Finding Even the Most Elusive Software 
 and Hardware Problems by David Agans • http://debuggingrules.com • Maniac Magee by Jerry Spinelli • https:/ /www.worldcat.org/oclc/20422223 Further Reading
52. Thanks!
 Questions?
 War stories?

53. @milsyobtaf