5 ms·

>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to <wiki link>. Set ENVVAR to a proper value and restart the service.” Really, s

>it could give direct advice: “PERFORM THESE STEPS: You must define ENVVAR. Go to <wiki link>. Set ENVVAR to a proper value and restart the service.” Really, should logs also be documentation now ? Just mindlessly logging the same "advice" over and over again each time the error happen ?

dementiapatent 4y ago
It will be so much fun when the implementation is refactored and half of these comments are forgotten about and no longer meaningful.
- prerok 4y ago
  Exactly. At one of my previous workplaces there was a cumulative effect of misattributed error messages so the actions to perform were often of no help. Not even to mention the fact that new or changed error messages caused a landslide in costs in translations to various languages. I guess this product has no localization? At that time, when I was working at such a product that had it, we had to go through a deliberate process to describe why we want to change it, what the impact is, etc. Tell me you want 100 new messages and you will be stuck in meetings for the next month. In their case, though, it seems they at least have the support in management for it. I hope it turns out better for them than it did for me.
  - SpicyLemonZest 4y ago
    I had an error message a few months ago that instructed me to reinstall the AWS CLI, I filed a ticket when that didn't work, and the team was annoyed with me because obviously the real problem was a Python configuration warning with no suggested action 10 lines up.
ddulaney 4y ago
Logs can definitely be a form of documentation. I write software that is generally run low in the stack, quietly doing some mundane tasks that are business-critical but rarely thought about. If one of our clients has to mess with our software beyond the occasional update, that was a failing. Not all software is like this, but lots of it is -- its value is that no human needs to be involved. I need to write log messages with the expectation of an audience who doesn't know much about the software -- it's been running uninterrupted for months or years and suddenly something has gone wrong. If the log line doesn't tell the user how to solve their problem, I will end up getting a call.
- throw827474737 4y ago
  If it is that simple, the why doesn't the code fix it itself? But no, usually there is 1/2/3 likely things, but it also could be anything else.. and that kind if unexpected errors even often have no default-fix. No, the most best thing is to point to the documentation which has that, and not printig out manpages of docs in error messages now. > I write software that is generally run low in the stack What stack, how low? Me too.. that low that I usually cannot return or even log a " see error code doc at http.." string for various reasons (bandwidth, mem, performance) but only have error codes ;)
  - pwinnski 4y ago
    In the case at hand, where an environment variable isn't set, how exactly should the code fix itself? Human interaction is necessary, which is the reason the log message should spell out what the human needs to do. If I'm starting a service and see a pointer in the logs to documentation, that seems like an incredibly broken approach to me. Why would I look at missing or out-of-date documentation that may or may not be at hand when the code that knows the problem is right there and can just tell me? A log message like you're describing might as well say, "Something went wrong, but I don't want to tell you what. Instead check page 43 of the document in the third file cabinet from the left in that room over there on your right. No, your other right."
    - samus 4y ago
      Similar issues arises with such documentation in error messages. There now has to be a process to make sure that all such information is always accounted for and updated correspondingly when the system changes. > Something went wrong, but I don't want to tell you what. is somewhat disingenius of an example. Error logs should tell in exhausting detail what went wrong. Ops needs that to analyse the situation, and the vendor will have much less trouble reproducing the error. However, suggesting specific fixes could be disastrous. Furthermore, documentation should already be in a form that operations can be expected to work with also in crisis situations.
  - an_ko 4y ago
chillfox 4y ago
Yes! We have tools to filter what gets saved and compression that handles repeated text very well. So why not provide docs on how to solve the error along with the error.
kortex 4y ago
It depends who, what, and when the error is about. Failures are generally a bathtub curve. You have a high rate at start (usually configuration issues), some fairly fixed rate during operation, and then more at end of lifecycle (exhaustion, service hiccups on scale-in). If it's in the early lifecycle, absolutely, because it's most actionable. X is set wrong, Y can't be reached, etc, guide whoever is operating the system how to fix it. If it's mid cycle, it's often post-hoc, but context is worth its weight in gold. Less about telling the operator how to fix and more about why it broke, to avoid in the future. End of cycle, whatever.
Spivak 4y ago
Errors on initialization, fatal errors, and non-recurrent errors that require human/support intervention should be documentation.
hinkley 4y ago
If the error results in the program shutting down, it’s once per fatal interaction. In other words, yes.
0xbadcafebee 4y ago
Logs actually are a form of documentation. Documentation can provide instructions on how to diagnose and fix problems, and that's what logs do: tell a human being what a problem is and how to fix it. Remember that often the person reading the logs is not the person who wrote the software. Maybe it's an Ops person at 2AM trying to fix a broken deploy. Maybe it's a developer who joined the company 3 years after the software was written. Maybe the log is passing through an error message from 3 layers deep in the stack. The more literate your logs are, the better.
eyelidlessness 4y ago
This is fairly common in good error logs.
pwinnski 4y ago
Yes! There are people who don't read formal documentation but do read logs, after all. If the advice is the same over and over again, then yes, give the advice over and over again. I wouldn't want to assume that someone has read every line of the logs, or has started to read top-to-bottom, so the advice should always be among the most recent lines in the log, and the only way to ensure that is to give the advice again each time the error happens.
xboxnolifes 4y ago
Should logs more clearly let the user know how to fix problems? Yes.

dementiapatent 4y ago

It will be so much fun when the implementation is refactored and half of these comments are forgotten about and no longer meaningful.

prerok 4y ago
Exactly. At one of my previous workplaces there was a cumulative effect of misattributed error messages so the actions to perform were often of no help. Not even to mention the fact that new or changed error messages caused a landslide in costs in translations to various languages. I guess this product has no localization? At that time, when I was working at such a product that had it, we had to go through a deliberate process to describe why we want to change it, what the impact is, etc. Tell me you want 100 new messages and you will be stuck in meetings for the next month. In their case, though, it seems they at least have the support in management for it. I hope it turns out better for them than it did for me.
- SpicyLemonZest 4y ago
  I had an error message a few months ago that instructed me to reinstall the AWS CLI, I filed a ticket when that didn't work, and the team was annoyed with me because obviously the real problem was a Python configuration warning with no suggested action 10 lines up.

ddulaney 4y ago

Logs can definitely be a form of documentation. I write software that is generally run low in the stack, quietly doing some mundane tasks that are business-critical but rarely thought about. If one of our clients has to mess with our software beyond the occasional update, that was a failing. Not all software is like this, but lots of it is -- its value is that no human needs to be involved. I need to write log messages with the expectation of an audience who doesn't know much about the software -- it's been running uninterrupted for months or years and suddenly something has gone wrong. If the log line doesn't tell the user how to solve their problem, I will end up getting a call.

throw827474737 4y ago
If it is that simple, the why doesn't the code fix it itself? But no, usually there is 1/2/3 likely things, but it also could be anything else.. and that kind if unexpected errors even often have no default-fix. No, the most best thing is to point to the documentation which has that, and not printig out manpages of docs in error messages now. > I write software that is generally run low in the stack What stack, how low? Me too.. that low that I usually cannot return or even log a " see error code doc at http.." string for various reasons (bandwidth, mem, performance) but only have error codes ;)
- pwinnski 4y ago
  In the case at hand, where an environment variable isn't set, how exactly should the code fix itself? Human interaction is necessary, which is the reason the log message should spell out what the human needs to do. If I'm starting a service and see a pointer in the logs to documentation, that seems like an incredibly broken approach to me. Why would I look at missing or out-of-date documentation that may or may not be at hand when the code that knows the problem is right there and can just tell me? A log message like you're describing might as well say, "Something went wrong, but I don't want to tell you what. Instead check page 43 of the document in the third file cabinet from the left in that room over there on your right. No, your other right."
  - samus 4y ago
    Similar issues arises with such documentation in error messages. There now has to be a process to make sure that all such information is always accounted for and updated correspondingly when the system changes. > Something went wrong, but I don't want to tell you what. is somewhat disingenius of an example. Error logs should tell in exhausting detail what went wrong. Ops needs that to analyse the situation, and the vendor will have much less trouble reproducing the error. However, suggesting specific fixes could be disastrous. Furthermore, documentation should already be in a form that operations can be expected to work with also in crisis situations.
- an_ko 4y ago

chillfox 4y ago

Yes! We have tools to filter what gets saved and compression that handles repeated text very well. So why not provide docs on how to solve the error along with the error.

kortex 4y ago

It depends who, what, and when the error is about. Failures are generally a bathtub curve. You have a high rate at start (usually configuration issues), some fairly fixed rate during operation, and then more at end of lifecycle (exhaustion, service hiccups on scale-in). If it's in the early lifecycle, absolutely, because it's most actionable. X is set wrong, Y can't be reached, etc, guide whoever is operating the system how to fix it. If it's mid cycle, it's often post-hoc, but context is worth its weight in gold. Less about telling the operator how to fix and more about why it broke, to avoid in the future. End of cycle, whatever.

Spivak 4y ago

Errors on initialization, fatal errors, and non-recurrent errors that require human/support intervention should be documentation.

hinkley 4y ago

If the error results in the program shutting down, it’s once per fatal interaction. In other words, yes.

0xbadcafebee 4y ago

Logs actually are a form of documentation. Documentation can provide instructions on how to diagnose and fix problems, and that's what logs do: tell a human being what a problem is and how to fix it. Remember that often the person reading the logs is not the person who wrote the software. Maybe it's an Ops person at 2AM trying to fix a broken deploy. Maybe it's a developer who joined the company 3 years after the software was written. Maybe the log is passing through an error message from 3 layers deep in the stack. The more literate your logs are, the better.

eyelidlessness 4y ago

This is fairly common in good error logs.

pwinnski 4y ago

Yes! There are people who don't read formal documentation but do read logs, after all. If the advice is the same over and over again, then yes, give the advice over and over again. I wouldn't want to assume that someone has read every line of the logs, or has started to read top-to-bottom, so the advice should always be among the most recent lines in the log, and the only way to ensure that is to give the advice again each time the error happens.

xboxnolifes 4y ago

Should logs more clearly let the user know how to fix problems? Yes.