Writing good log messages is part design, part good practice, part knowing what and when to say it.

Design

(1) You need to decide what exactly you hope to get out of a logging session. Are you going to be debugging bugs, crashes, or other critical events like a forensic accountant or like a whack-a-mole?

(2) Are you going to use flat files, how big will they get, how many files will you keep around? All very important when thinking about backups, disk space, maintenance, recovery, and so on. You might also be thinking about the different versions of syslog-like tools where you can ship the events remotely.

(3) Are you going to store the logs in a DB on the local system and then use sharding to allow for more permanent maintenance? This is interesting because the searching can be easier than grep, awk, etc… Also, considering (4) grouping related messages is easier and you can use SQL-like reporting tools.

(4) Are there some pre-optimizations you want to perform like all logged entries are stored in temp storage until the transaction is complete. Then the data is shipped to the repository for storage.

Good Practice

Treat all of your code the same.  Whatever level of logging you are performing you should be consistant throughout your application. This way you will not be surprised by your results and you will not have to worry about “and then a miracle occurred)

What to Say, Where to Say it

If you are processing transactions then make sure that you create a transaction ID as soon as possible and start using that ID with every log message related to this transaction. This is necessary so that you have a thru-line and so the transaction can be traced.

Also make sure that you are clear as to the intent of the function and what the results were. That also means that the type of entry should make sense. INFO, WARN, ERROR, EXCEPTION and so on.

You might even time the execution of the function.

Warning

One thing to be wary of. Logging can consume your disk, disk I/O, CPU, memory, message queues, database. You can spend more time copying, moving, and filtering your messages that it might effect the ability to produce meaningful results.

For example, using a Redis pub/sub in order to log transactions might seem like a good idea, however, if you consume all of system memory you may end up swapping and then net result is going to be poor performance.