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

Improper english

Before retirement ended my last spell of unemployment, i wondered if the timing of that dismissal was ideal. one month earlier or later might have been better? improving a server log was my last assignment. like many other companies, their senior management believed in their culture, technology, and tools. like other well-funded companies, they used Splunk and wanted to use JSON format. nobody reviewed the pull request that would have established a baseline for my work. their Splunk dashboard code was not versioned. Overcommunicating JSON can be ideal, and creating a data structure to discover if a log entry describes an error is easy and reasonably fast, but computers find strings very quickly. a faster algorithm uses less electricity; computer activity is human activity. ...
Post a Comment
Read more

Obsolete versions

Once upon a time, upgrading packages was just downloading and installing files. after a while, it also entailed compiling source code because my operating systems no longer received first-class support. Descent Into Madness after a while, upgrading a package also entailed upgrading the tools needed to make it and their dependencies. i felt like i had installed every (meta-)build system. on one of my MacBooks, Homebrew maintained two versions of Python and two versions of llvm . as projects migrated from Autotools to CMake, library versions became inconsistent. these inconsistencies puzzled me, because the first test one should perform after adding support for another build system is determining if the result is the same. any differences should be eliminated/explained. in real life, most people didn't ...
Post a Comment
Read more

Cat's whiskers

Online forums are good sources of information and/or habitats for groupthink. Jean Valjean ignored the smell; so can you :-) forums are biased in various ways. for example, woodworkers' opinions about linseed oil are informed by wood finish products. in another forum, we might find a recommendation for finishing wood with linseed oil sold by an art supply store. sauce for the painter is sauce for the woodworker? Slippery when wet when i became interested in safety razors, forums were invaluable sources of information. they are still helpful, but i learned enough to continue on my own. at one point i bought cheap shaving soap thinking that it couldn't be as bad as forum contributors claimed. they were right, but the soap was/is still useful: it stays at th...
Post a Comment
Read more