4 ms·

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-cri

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
  I don't want to have to hunt for documentation if it breaks. It may have been 30 years and everything but the binary has been lost, and the vendor is out of business. If in that situation all I get is an error code and a link to documentation that doesn't exist, I'd have to start reverse-engineering. And while doing so I'd definitely be cursing the coder who decided that saving a couple hundred bytes of space in a log file in the event of an "abort the program"-severity event was worth dumping this in my lap.
  - samus 4y ago
    Running such software is asking for a disaster already. At least documentation should still exist, and operational frameworks like ITIL insist on that. It can happen, but is usually telling of an operational culture that disregards maintenance, counting on being able to kick the can down the road as long as possible.

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
I don't want to have to hunt for documentation if it breaks. It may have been 30 years and everything but the binary has been lost, and the vendor is out of business. If in that situation all I get is an error code and a link to documentation that doesn't exist, I'd have to start reverse-engineering. And while doing so I'd definitely be cursing the coder who decided that saving a couple hundred bytes of space in a log file in the event of an "abort the program"-severity event was worth dumping this in my lap.
- samus 4y ago
  Running such software is asking for a disaster already. At least documentation should still exist, and operational frameworks like ITIL insist on that. It can happen, but is usually telling of an operational culture that disregards maintenance, counting on being able to kick the can down the road as long as possible.