Monitoring Is a Pain
I have achieved zen with logs.<p>Levels are easy.  You have three, DEBUG, INFO, and ERROR.  DEBUG is stuff that&#x27;s interesting to you, the author of the code.  INFO is things that are interesting to the person&#x2F;team that runs your software in production.  ERROR is for things that require human attention.<p>My opinion is that INFO logs are the primary user interface for your server-side software, and demand the level of attention that you would expect a frontend designer to devote to your brand or whatever.  That&#x27;s where the software gets to interface with the person that&#x27;s responsible for its care and feeding.  Garbage in there wastes their time.  Everything in INFO should be logged for a reason.  (Yes, sometimes there&#x27;s spam.  Usually request&#x2F;response data.  Most of the time the requests go great, but you don&#x27;t know they&#x27;ve gone great until you&#x27;ve logged the fact that they were made.  It&#x27;s a necessary evil.)<p>Meanwhile, DEBUG should probably be pretty chatty.  If your program is consuming resources like CPU, it better justify itself in the DEBUG logs.  A program sitting there using 100% of the CPU and not logging anything at level DEBUG is very very suspicious.  My philosophy is to &quot;show your work&quot; on every critical operation.  Log when something starts, what decisions it makes along the way, and when it&#x27;s done.  A message like &quot;failed to contact server example.com: i&#x2F;o timeout after 10 minutes&quot; is 10 minutes too late to be interesting.   &quot;connect to example.com: started&quot;, &quot;connect to example.com: i&#x2F;o timeout after 10 minutes&quot; is much better, because 10 minutes before the error you can read the logs and realize example.com is NOT where your database is hosted.  (You can really go overboard here and I would never stop you.  connect to example.com: resolve DNS: start, connect to example.com: resolve DNS: A 1.2.3.4, connect to example.com: dial 1.2.3.4: start, ....  In production, I compromise and log &quot;start&quot;, &quot;ongoing long HTTP request&quot; (at 10 seconds), and &quot;finished&quot; with the status code.)  Every branch is a place to log which branch you selected and why.  If there&#x27;s a bug and you only know the outcome, but not the software&#x27;s &quot;thought process&quot; that led you there, you have nothing to go on.  &quot;Hey, the FrobTheBaz endpoint is returning 400s.&quot;  That is useless information.  You have to read the code and guess.  You do not want to be guessing during an outage.<p>Errors are a whole can of worms.  If someone reading the logs can&#x27;t fix the problem, it&#x27;s not an error.  &quot;Error: cannot write data to the database&quot;.  That&#x27;s a big problem.  Disconnect that popcorn popper and plug the power cable to your database back in! &quot;Error: login for root from spambot@1.2.3.4: invalid signature&quot; is a problem for your firewall.  What is someone reading the logs going to do about that?  Call up 1.2.3.4 and ask them to stop guessing SSH keys?  At best, that&#x27;s an INFO log.  There are 3.4 with 38 zeros possible keys.  They aren&#x27;t ever going to guess it.  If you decide &quot;this isn&#x27;t even worth logging&quot;, I can definitely agree with you.  (I&#x27;d log it, though.  An increase in failure attempts is good ancillary information when something else draws your attention to the system.)<p>Finally, newline-delimited JSON (&quot;jsonl&quot;) is the only correct format for logs.  Nobody wants to write a parser to figure out &quot;how many 400s did we serve today&quot;.  Just let JQ [<a href="https:&#x2F;&#x2F;jqlang.github.io&#x2F;jq&#x2F;" rel="nofollow noreferrer">https:&#x2F;&#x2F;jqlang.github.io&#x2F;jq&#x2F;</a>] do it for you.  If you want pretty colors for viewing, use something like jlog: <a href="https:&#x2F;&#x2F;github.com&#x2F;jrockway&#x2F;json-logs">https:&#x2F;&#x2F;github.com&#x2F;jrockway&#x2F;json-logs</a>.  You don&#x27;t need to write VT100 control characters to your log file.  I know for a fact you don&#x27;t even <i>have</i> a VT100.<p>All other formats of telemetry are just logs with fancier user interfaces.  Metrics?  Just write them out to your logs: &quot;meter:http_bytes_sent delta:16384 x-request-id:813db394-75a1-4b22-94ad-e7850d9cdd25&quot;.  You still have the ability to tail your logs and convert the metrics to a proper time series database (with less cardinality than &quot;per request&quot; of course), but you can now also do investigations in context.  For example, I&#x27;ve implemented exactly this system at work.  A customer shows up, saying that we&#x27;re using too much memory.  I ask for the logs and see something like &quot;span start: compaction&quot;, &quot;meter:self_rss_bytes delta:2000000000&quot;, &quot;span end: compaction, error:nil&quot;, &quot;meter:self_rss_bytes delta:-1000000000&quot;.  Hey, we leaked a gig of RAM in compaction.  You would never figure out the memory leak with &quot;compaction done after 5 minutes&quot; and a graph of memory usage across your fleet.<p>While you weren&#x27;t looking I also threw traces in there!  Have a logging primitive like Span(&quot;operate(foo)&quot;, func { ... }) that logs the start and the end, and throw a generated ID in every message.  Concatenate the span IDs which each recursive call to Span (I abuse context.Context for this, sorry Rob Pike), and log them with every message in the span.  Now you have distributed tracing.  As always, sure, parse those logs and throw the log-less spans in to Jaeger so you can efficiently search for rare events and have a nice data flow graph or whatever.<p>Log sare so simple and so great.  The problem you run into is by not producing enough of them.  Disks cost nothing.  You can delete the debug logs after a short period of time, or not even produce them until you suspect an issue.  Don&#x27;t sweat the log levels; pick the 3 I picked and try to enforce the rules in code review.  Aim the log messages at the right audience; dev team, ops team, emergencies.  Show your work.  Log contextual information.  Put metrics in the logs, and aggregate them for dashboards and monitoring.  Annotate logs with trace IDs, and put those into Jaeger.  You&#x27;ll never have to <i>wonder</i> why your system is broken again; you printed out everything it&#x27;s doing.   The aggregation will tell you you&#x27;re not meeting your error budget, and the logs for a representative request will tell you why that one failed. 
 Once you know what&#x27;s broken, the fix is always easy.<p>Whenever I tell people my system, they tell me it can&#x27;t scale.  When I worked at Google, I wrote exactly this system for monitoring Google Fiber (well, we didn&#x27;t have log levels really...), and we could answer questions about the entire CPE fleet as easily as we could answer questions about one device or one bug.  Over many years, I&#x27;ve finally gotten this into the &quot;real world&quot; (like weeks ago), and it&#x27;s been amazing.<p>Good logs are the best thing you can do for someone that has to run your software.  For a lot of folks, that&#x27;s you!  For other folks, that&#x27;s your customers.  Can you customer set up Prometheus, ElasticSearch, and Jaeger, and dump that all out and send it to you in Slack?  Unlikely.  Can they dump a file that&#x27;s 10MB of JSON lines into Slack?  They sure can.  And now you can diagnose the bug and fix it without bothering them for more info.  It&#x27;s good for everyone.