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
   

   View Slide

2. Howdy!
   Dustin Younse
   @milsyobtaf
   I’m an engineer at
   Acquia
   

   View Slide

3. What Is Debugging?
   

   View Slide

4. Nothing But Text?
   

   View Slide

5. • CSS aggregated but not cached
   • JS blocked in the browser
   • File permissions in sites/default/files
   Nothing But Text?
   

   View Slide

6. • Mostly a semantic difference
   • 5 minutes vs 5 hours?
   • “Fixed” vs understood and corrected
   Debugging vs Troubleshooting
   

   View Slide

7. What Is The Black Box?
   

   View Slide

8. • Non-technical education
   • Self taught web skills
   • Above average Googling abilities
   • Late nights staring at error messages
   A Familiar Story?
   

   View Slide

9. What Is Drupal?
   

   View Slide

10. Mental Model of Drupal
    

    View Slide

11. Mental Model of Drupal
    

    View Slide

12. Mental Model of Drupal
    

    View Slide

13. Mental Model of Drupal
    

    View Slide

14. Mental Model of Drupal
    

    View Slide

15. Start At The Beginning
    

    View Slide

16. When All You Have Is A Hammer
    CC by 2.0 https://www.flickr.com/photos/raindrift/7095238893/
    

    View Slide

17. Text Editors
    • “Text Editors”
    • Text Editors
    • IDEs
    

    View Slide

18. • Notepad (Windows)
    • Text Edit (Mac)
    • Nano (Linux / Mac)
    “Text Editors”
    

    View Slide

19. • Notepad++ (Windows)
    • vim (Mac / Linux)
    • Dreamweaver (Mac / Windows)
    • Sublime Text (Mac / Linux / Windows)
    • Atom (Mac / Linux / Windows)
    Text Editors
    

    View Slide

20. • PHPStorm (Mac / Linux / Windows)
    • Eclipse (Mac / Linux / Windows)
    • Komodo (Mac / Linux / Windows)
    Integrated Development
    Environments
    

    View Slide

21. • emacs (Mac / Linux / Unix / Everything else)
    Operating Systems With Built
    In Text Editors
    

    View Slide

22. Development Environments
    • On your server
    • On your machine
    • On your machine, but it acts like the server
    

    View Slide

23. Development Environments
    • FTP Development
    • “Cowboy coding”
    • Local Environments
    • MAMP / LAMP / Vagrant
    • Next generation
    • Kalabox
    • DrupalVM
    

    View Slide

24. • FTP Development
    • “Cowboy coding”
    • No version control up front
    • Little debugging visibility
    • Log files (maybe), debug statements
    • Watchdog logs (maybe)
    FTP Development
    

    View Slide

25. • print_r()
    • Raw dump of a variable or context, no formatting
    • print_r($node);
    •
    • dsm() / kint()
    • Formatted dump of a variable or context
    • dsm($node);
    Debug Statements in Code
    

    View Slide

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
    

    View Slide

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
    

    View Slide

28. What’s xdebug?
    

    View Slide

29. • Hitting pause on code execution
    • Inspecting the current state of “the stack”
    • Modifying values live
    xdebug: Step Through
    Debugging
    

    View Slide

30. Something Is Broken!
    

    View Slide

31. View Slide

32. Relax.
    

    View Slide

33. Remember Cobble’s Knot
    

    View Slide

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?
    

    View Slide

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
    

    View Slide

36. • Custom Module
    • template.php / .theme file
    • Theme Template
    Where Is It Broken?
    

    View Slide

37. View Slide

38. The Scientific Method
    

    View Slide

39. • Change one thing at a time
    • Test that change
    • Repeat
    Finally, Debugging
    

    View Slide

40. • Save your progress as you work
    • Recreate your Features or config yml
    • Makes rabbit holes manageable
    git Is Your Friend
    

    View Slide

41. • Let’s you isolate changes between commits
    git bisect Is Your Friend
    

    View Slide

42. git bisect Is Your Friend
    

    View Slide

43. git bisect Is Your Friend
    

    View Slide

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
    

    View Slide

45. git blame Finds Your Enemies
    

    View Slide

46. git blame Finds Your Enemies
    

    View Slide

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
    

    View Slide

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
    

    View Slide

49. Make The Future Easier
    

    View Slide

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
    

    View Slide

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
    

    View Slide

52. Thanks!

    Questions?

    War stories?

    

    View Slide

53. @milsyobtaf
    

    View Slide