From 9bbd3fb16d37298650c35fe25327fe06ec44ab2c Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Mon, 1 Jul 2019 19:55:51 -0300 Subject: [PATCH] New chapter: Logs for events --- content/books/things-i-learnt/_index.md | 1 + .../languages-are-more/index.md | 2 +- .../books/things-i-learnt/log-events/index.md | 44 +++++++++++++++++++ .../things-i-learnt/start-stupid/index.md | 2 +- 4 files changed, 47 insertions(+), 2 deletions(-) create mode 100644 content/books/things-i-learnt/log-events/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 927de42..3190069 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -42,6 +42,7 @@ template = "section-contentless.html" * [Always Use Timezones With Your Dates](use-timezones) * [Always Use UTF-8 For Your Strings](use-utf8) * [Start Stupid](start-stupid) + * [Logs Are For Events, Not User Interface](log-events) * Community/Teams * [A Language Is Much More Than A Language](languages-are-more) * [Understand And Stay Away From Cargo Cult](cargo-cult) diff --git a/content/books/things-i-learnt/languages-are-more/index.md b/content/books/things-i-learnt/languages-are-more/index.md index 9e4dbea..827bc93 100644 --- a/content/books/things-i-learnt/languages-are-more/index.md +++ b/content/books/things-i-learnt/languages-are-more/index.md @@ -39,4 +39,4 @@ surface of what the whole of a language encapsulates and if you ignore the other elements in it, you may find yourself with a cute language in a community that is always fighting and never going forward. -{{ chapters(prev_chapter_link="/books/things-i-learnt/start-stupid", prev_chapter_title="Start Stupid", next_chapter_link="/books/things-i-learnt/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/log-events", prev_chapter_title="Logs Are For Events, Not User Interface", next_chapter_link="/books/things-i-learnt/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }} diff --git a/content/books/things-i-learnt/log-events/index.md b/content/books/things-i-learnt/log-events/index.md new file mode 100644 index 0000000..311fc95 --- /dev/null +++ b/content/books/things-i-learnt/log-events/index.md @@ -0,0 +1,44 @@ ++++ +title = "Things I Learnt The Hard Way - Logs Are For Events, Not User Interface" +date = 2019-07-01 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "logs", "ui"] ++++ + +Two things in one: First of all, when using logging, use it to log events, not +for user interfaces; second, log _events_ in a machine readable way, not +necessarily an human readable format. + + + +For a long time, I used logs to show to the user what was happening. Nothing +could be the idea of displaying errors, general information and, if the user +requested, the internals of whatever is going on in one simple way. I mean, +yeah, let me add the errors, the info messages and the debug messages and let +the user decide what they want to see. + +But that's not what logs are targeted for -- and now I'm having to rethink +most of the stuff I already wrote. + +Use the standard output to inform the user what's going on, in a human +readable format; use the standard err to inform the user when things go wrong; +but use the logs to capture something that you'll have to process later, so +you should probably use a format that it is easier to parse, even if it is not +so friendly. + +As an example, let's say you're connecting to a server. You could use the +standard output to say "Connecting to server", to give the user a feedback +about what's going on; at the same time, you could log "CONNECTION +[SERVER]", with the IP/Name of the server you're connecting. Surely, the +"CONNECTION" word is not that friendly to the user, but if you had to parse +the line, it would be really easy, wouldn't it? + +Another example: If your application is adding a record to the database, there +is nothing wrong logging "ADDING_RECORD: field=value; field=value; +field=value" 'cause, in case something goes wrong while saving the record, you +could have the values to try to figure out why it failed -- surely, logging +why it failed also helps, but you know what I mean. This is an example of +something that makes complete sense in logs, but not in user interfaces. + +{{ chapters(prev_chapter_link="/books/things-i-learnt/start-stupid", prev_chapter_title="Start Stupid", next_chapter_link="/books/things-i-learnt/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }} diff --git a/content/books/things-i-learnt/start-stupid/index.md b/content/books/things-i-learnt/start-stupid/index.md index 64e1ef9..ade4987 100644 --- a/content/books/things-i-learnt/start-stupid/index.md +++ b/content/books/things-i-learnt/start-stupid/index.md @@ -30,4 +30,4 @@ what your IDE is doing. And when you grasp that, you'll be able to use _any_ IDE. -{{ chapters(prev_chapter_link="/books/things-i-learnt/use-utf8", prev_chapter_title="Always Use UTF-8 For Your Strings", next_chapter_link="/books/things-i-learnt/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/use-utf8", prev_chapter_title="Always Use UTF-8 For Your Strings", next_chapter_link="/books/things-i-learnt/log-events", next_chapter_title="Logs Are For Events, Not User Interface") }}