Programming

1. Don’t Write Logs by Yourself (AKA Don’t Reinvent the Wheel)

2. Log at the Proper Level

3. Employ the Proper Log Category

4. Write Meaningful Log Messages

5. Write Log Messages in English

6. Add Context to Your Log Messages

7. Log in Machine Parseable Format

8. But Make the Logs Human-Readable as Well

9. Don’t Log Too Much or Too LittlE

10. Think of Your Audience

11. Don’t Log for Troubleshooting Purposes Only

12. Avoid Vendor Lock-In

13. Don’t Log Sensitive Information

The article goes into some nice detail on each of these but those are the 13 practices being advocated.

So, if you just use the system API, then this means logging with syslog(3). Learn how to use it.

This is old advice. These days just log to stdout, no need for your process to understand syslog, systemd, containers and modern systems just capture stdout and forward that where it needs to do. Then all applications can be simple and it us up to the system to handle them in a consistent way.

NOTICE level: this will certainly be the level at which the program will run when in production

I have never see anyone use this log level ever. Most use or default to Info or Warn. Even the author later says

I run my server code at level INFO usually, but my desktop programs run at level DEBUG.

If your message uses a special charset or even UTF-8, it might not render correctly at the end, but worst it could be corrupted in transit and become unreadable.

I don't know if this is true anymore. UTF-8 is ubiquitous these days and I would be surprised if any logging system could not handle it, or at least any modern one. I am very tempted to start adding some emoji to my logs to find out though.

User 54543 successfully registered e-mail user@domain.com

Now that is a big no no. Never ever log PII data if you don't want a world of hurt later on.

2013-01-12 17:49:37,656 [T1] INFO c.d.g.UserRequest User plays {'user':1334563, 'card':'4 of spade', 'game':23425656}

I do not like that at all. The message should not contain json. Most logging libraries let you add context in a consistent way and can output the whole log line in Json. Having escaped json in json because you decided to add json manually is a pain, just use the tools you are given properly.

Add timestamps either in UTC or local time plus offset

Never log in local time. DST fucks shit up when you do that. Use UTC for everything and convert when displayed if needed, but always store dates in UTC.

Think of Your Audience

Very much this. I have seen far too many error message that give fuck all context to the problem and require diving through source code to figure out the hell went wrong. Think about how logs will be read without the context of the source code at hand.