Foundations of Debugging for Golang (Matthew Boyle)（Z-Library）

FOUNDATIONS OF DEBUGGING FOR GOLANG MATTHEW BOYLE

Copyright © 2024 by byteSizeGo All rights reserved. No part of this book may be reproduced in any form or by any electronic or mechanical means, including information storage and retrieval systems, without written permission from the author, except for the use of brief quotations in a book review. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor byteSizeGo or its dealers and distributors, will be held liable for any damages caused or alleged to have been caused directly or indirectly by this book.

C O N T R I B U T O R S A B O U T T H E AU T H O R Matt Boyle is an experienced technical leader in the field of distributed systems, specializing in using Go. He has worked at huge companies such as Cloudflare and General Electric, as well as exciting high-growth startups such as Curve and Crowdcube. Matt has been writing Go for production since 2018 and often shares blog posts and fun trivia about Go over on Twitter (@Matt‐ JamesBoyle1).

A B O U T T H E T EC H N I C A L R E V I E W E R S Ansar Smagulov is a full-stack engineering lead specializing in Go and TypeScript. Ansar has led teams and projects at Central Asia's largest cloud provider, PS Cloud Services. He also develops Zen, a free and efficient privacy guard for desktop operating systems, among other open- source projects. You can find more about Ansar's open source work at GitHub (@anfragment2). Toni Lovejoy is an experienced software engineer who has been writing production Go code for the last 5 years. With much of her experience in high growth startups such as StockX. She has given back to the community teaching backend coding at bootcamps and volunteering her time teaching coding to youth. You can reach Toni on Linkedin3. Swastik Baranwal is an open-source developer. He has been contributing to The V Programming Language4 as one of the core developers and has greatly impacted the open-source community and projects. His interest lies in system programming and continuously learning new technologies. He is open to working full-time as well as part-time roles. To learn more about him, you can visit his website https://swastik.is- a.dev/

Michael Bang is a pragmatic developer that loves to spend his time building maintainable and well-tested software. He fell in love with Go more than a decade ago and has used it happily ever since. He loves helping the community in small ways from the shadows; Foundations of Debugging for Golang is the fourth book he has contributed to as a technical reviewer. If you need help with a technical book, you're welcome to reach out to @micvbang5.

C O N T E N T S 1. WELCOME! 1 2. WHAT IS DEBUGGING AND WHY DO WE DO IT? 3 METHODS OF DEBUGGING 1. DEBUGGING BY EYE 9 A Simple Exercise 10 Strategies for Effective Code Inspection 12 Learning Code Patterns and Being Aware of Common Errors 13 Error Handling 13 Interfaces 14 Concurrency 14 Styleguides 14 Another Exercise 15 Wrapping Up 16 2. PAIR PROGRAMMING 18 What is Pair Programming? 19 The Driver and the Navigator 19 Switching Roles 19 The Power of Two Minds 19 Accelerating Learning and Knowledge Transfer 20 Building Rapport and Fostering Communication 20 To Pair or Not to Pair? 21 Tips for Being a Great Driver 21 Tips for Being a Great Navigator 23 Pairing Remotely 24 How I have Used Pair Programming to Solve Production Issues 25 3. LOGGING 29 Logging Locally with the fmt package 30 Upgrading Logs With the Log Package 32 So Which should I use for local logging? 35 Slog 35

Creating a Logging Strategy 39 What should I do with all these logs? 41 An Exercise 42 Wrapping Up 47 4. THE DEBUGGER 49 Setting up the Debugger in VSCode 50 Setting up the Debugger in Goland 51 Breakpoints 52 Debugging Panic Traces 58 Stepping Over 60 Stepping Into 61 Conditional Breakpoints 63 Debugging goroutines 65 Tests as an Entrypoint to Debugging 71 You Try - Exercise 74 DEBUGGING IN PRODUCTION 1. METRICS 79 What are Metrics? 80 Categories of Metrics 80 Prometheus metric types 82 Adding metrics to a Go Application 83 Exposing Metrics 87 Viewing Metrics 88 Introduction to PromQL 90 Using Metrics to help you Debug Production 92 Alerting 95 Exercise 96 A Warning on Measuring Too Much 96 2. DISTRIBUTED TRACING 99 Open Telemetry 100 Adding Traces to a Go API 101 Adding Attributes to Spans 109 Capturing Errors 110 Tracing Between Different Services 111 Automatic Dependency Maps 119 Tracing Beyond HTTP 121

Your Turn! 121 Wrapping Up with a Warning 122 3. PROFILING & PPROF 124 Why Profile? 125 Adding Profling - the simple way 126 Profling without Side effects 129 Profiling the heap (memory) 131 CPU Tracing and pprof List 140 Profiling goroutine Usage 148 Exercise 154 Wrapping Up - Should I Just Leave pprof Running all the Time? 155 4. THANK YOU 157 Notes 159

W W E L C O M E ! elcome to this book, Foundations of Debugging for Golang. I believe debugging is probably the most important skill that most people are never taught. Being able to debug locally and in production is a critical skill for any Go engineer, but it is rarely taught explicitly. It has taken me many years of working with Go in production to get comfortable debugging, and I want to accelerate your learning by teaching you everything I wish I had known when I started out. This book started life as a course and was turned into a book by popular request. If you are a junior or mid-level Go engineer, I think this book will be useful for you. I have written this book from the ground up, but the content still overlaps with the course somewhat. If you are more of a visual learner like me, and as a thank you for buying this book, you can get 20% off the course from https://bytesizego.com using the code BOOK20. 1

M AT T H E W B OY LE When people think of debugging, they often think of the debugger. We will cover how to use the debugger in this book, but it is a small part of our debugging utility belt. We will also cover: How to get better at spotting issues by eye. Logging patterns. Metrics. Distributed Tracing. Profiling & Pprof. If you don’t know what any of those things are, do not worry, as by the end of this book you will. I hope you enjoy this book and I look forward to hearing what you think! The best way to reach me is over on Twitter (or X): @matt‐ jamesboyle. 1 - Matt Boyle 2

D W H AT I S D E B U G G I N G A N D W H Y D O W E D O I T ? ebugging is an essential part of programming. It refers to the process of identifying, analyzing, and fixing issues in code. The term "debugging" originates from a fascinating story involving computer pioneer Grace Hopper. Whilst working on the Harvard Mark II computer in the 1940s, Hopper's team encountered a system malfunction. Upon investiga‐ tion, they discovered a literal bug - a moth stuck in one of the machine's mechanical relays! The bug was causing the relay to fail, leading to errors. Hopper's team removed the moth, taped it to their logbook, and coined the term "debugging" to describe fixing the glitch. 3

M AT T H E W B OY LE When debugging code ourselves, it helps to think of Grace Hopper's moth and methodically follow discrete steps: Firstly, we need to identify the bug This can be tricky, as some only appear in specific situations like high load. Having robust logging and monitoring helps detect bugs early. Furthermore, writing comprehensive tests also surfaces issues before they impact users. We will not talk about writing tests in this book, but we will discuss how to debug them. Secondly, we analyze the problem to determine the best fix Should we add a quick if statement as a patch? Should we do a bigger refactor? Each approach has its merits. The former tackles the imme‐ diate issue. However, considering the long-term perspective, the refactor is likely a better solution. If the bug is surfaced in an ongoing incident, I would often recom‐ mend making the quickest fix you can for now to remove customer impact (after ensuring we have captured the information we need to follow up later). We can make a ticket on the backlog for the bigger refactor. Finally, we implement the fix and update associated tests. This ensures the bug stays fixed and the new code maintains integrity. Debugging techniques range from carefully reading code to advanced tooling. Thankfully, Go provides excellent built-in tools. From simple print statement debugging to robust profilers and tracers, Go makes finding and fixing bugs easy. 4

FO U N DAT I O N S O F D E B U G G I N G FO R G O L A N G Learning to debug will make you a better software engineer. Mastering the various debugging techniques will enable you to iden‐ tify and resolve issues more efficiently. Debugging is challenging but rewarding. With practice, you will build skills to create reliable, robust applications. Just like Grace Hopper debugging the Harvard Mark II, we too can methodically squash the bugs in our code! 5

METHODS OF DEBUGGING In this section we will start by learning some high level techniques for getting better at debugging (such as how to get better at spotting them by eye or pairing with a buddy). After that, we will dive into logging and discuss strategies for how to ensure you don’t log too much; a common problem I see. We’ll finish the chapter out by learning about the debugger, ensuring you can get it setup and we’ll learn some more advanced techniques for using it. I hope you enjoy it and learn a bunch!