Skip to main content

Deliberate logging

redacted log entries

While diagnosing an error, it's not unusual to discover that the application log does not contain relevant information while also being overly verbose. DEBUG-level entries can be cryptic, and maintainers often insist that their applications emit them in “production” environments. the universal acceptance of low quality logs is a management failure.

Holistic development

a software development protocol should synergize best practices, but we should run away whenever someone claims that success depends on a protocol's complete implementation. incremental development of software is common, as is reusing large frameworks. the development process can mature similarly.

Holistic Development is a protocol i should describe someday, but piecemeal presentation makes sense because partial implementation is helpful. each of its facets is client-facing. the application log is one of them.

Target audience

the application log is a generated document. its content is determined by application usage, and its audience includes three groups:

  • product owners want to know what an application did
  • people responsible for monitoring an application want to know if it's healthy
  • people responsible for maintaining an application want to know why it fails

a log should address people who know nothing about the implementation that generated it. its entries should be linguistically and stylistically consistent.

Log levels

Python's root logger is created with level WARNING, but none of the C++/C# applications i maintained used this level. an application should describe its actions with INFO-level entries, and use other levels to present explanatory details, e.g. errors.

at one point, i omitted the level name from DEBUG- and INFO-level entries because it seemed unnecessary. now i omit the level name from INFO-level entries, and use DEBUG level for issues that are often resolved by retrying.

Unicode symbols

many road signs use symbols instead of text, a preference that was ratified in 1931. every logging system supports UTF-8, so there is no reason to limit log entries to the ASCII character set.

log symbols may belong to meaningful categories. for example, i like to use media control symbols to communicate server status.

An example

the redacted image's log entries are from a server that reads my mail, scrapes websites, and uses third-party REST APIs to discover items of interest. this server provides a framework for data source-specific modules specified by a configuration file. this framework does various things on behalf of these modules, e.g. error handling (retrying) and logging.

each source has a display name, e.g. DMARC. source status is often symbolic, e.g. an envelope (✉) indicates that there are no failures in the DMARC aggregate report i just received (so i can delete the message without reviewing the report).

this server disables DEBUG-level entries by default, enabling them when it detects an issue. after noticing an issue, i usually disable DEBUG-level entries via the server's REST API. in this excerpt, the issue is my neglecting to let sources specify their HTTPConnection timeout.

Labels:

Comments

Post a Comment

Popular posts from this blog

Hoppin' John

Classic recipes born in poverty can be revised to take advantage of things we take for granted. in particular, many dishes traditionally cooked in one pot benefit from separation. on the other hand, we should respect timeless combinations of flavors and textures. ain't nothing like the real thing. Pork off cuts are authentic because this was a slave's dish, but i prefer bacon. ham hocks can taste a bit coarse and deboning them is a chore. i always have salt pork on hand, but it would require rinsing. in general, do not buy packaged bacon unless it's deeply discounted and reasonably lean. packaged ends/pieces can be easier to use and always cost less than slices. when a butcher displays the lean end of a slab, buy all of it. for this dish, i want bite-sized piec...
Post a Comment
Read more

Bourne to grep

And now for something completely different: a stupid script trick ... once upon a time, i worked with two software developers who had just started their careers. after giving them a script, one of them complained that it didn't support the --help option. the script was about ten lines including its shebang, without conditional expressions or complexity of any kind. i defended its informality by noting that scripts are text files, so developers can easily discover how to use them. my response had no effect, but i still think scripts written for members of the same development team may be less formal/helpful than usual. since then, i did change my mind about one thing: for a long time, i used Python whenever statements were conditionally executed. i use the Bourne shell more often now.
Post a Comment
Read more

Wake up and smell the glove

After mistakenly buying a large bag of ground coffee, i decided to learn the cold brew process. in the same way that pickleball is similar to badminton, cold steeping resembles espresso and pour over coffee. even though there are obvious differences, some things never change. Grind grind size usually affects extraction, but it has no effect here. on the other hand, it always affects filtration and i get very different results without reconfiguring my grinder (Orphan Espresso Lido 2). for various reasons, i steep in a medium saucepan. first, i add crumbled star anise (because i own too much of it). then, i grind coffee directly into the saucepan. Pour i pour water around the perimeter of the saucepan to prevent ground cof...
Post a Comment
Read more