Thursday, August 21, 2014

Truncated Logs and Trees

When asking someone else for help it can be tricky to adjust between the information rich and bandwidth constrained worlds of the real and the virtual. If I have a tree at the bottom of my garden which loses all its leaves one summer then the conversation with an expert on tree disease would go something like this:

"Hello Dave the tree expert," I would say.

"Hi Toby, what's up?" he would reply.

"I think the tree at the bottom of my garden is dying."

Dave would then start to investigate, "Why do you think that?"

"Because it's lost all its leaves," I'd say.

"Hmmm," he would say as he stroked his chin with his hand, "did they all drop over a couple of days? Or was it over a period of weeks?"

The conversation would then continue to go back and forth between us with Dave asking various questions to narrow down the issue. Unless I'd had too much coffee that day I would be very unlikely to approach Dave and say:

"Hi Dave," I'd blurt out.

He would just have time to say, "Oh Hello Toby-"

I would then interrupt him and say, "I have a tree. It's dying. It's at the end of my garden. I have just got a new cat. All the leaves fell off the tree. They were green, but went brown before dropping off. They have a strange white haze on them. The neighbour has just had some building work done right next to the corner the tree is in. I had waffles for breakfast. I just planted a row of lavender at the other end of my garden. The tree trunk looks the same as always. It's been a dry summer, but the winter was very damp."

Trying to throw all this information at the person in one go, without knowing what is relevant and what isn't, just doesn't work as an efficient way to communicate. In fact it is generally the case that the best problem solvers in any given area aren't the experts with the most in-depth knowledge but the ones who know the right questions to ask, as well as what order to ask them in. However with computer systems this is not generally the case.

Most pieces of computer software produce logs. These contain a history of events and observations that the software has made about the world. They can be very useful for tracking down why a program is behaving in a particular way, especially if the information which is chosen to be logged describes the state of the system sufficiently.

When asking someone for help you should always give them full access to the logs. First you should described the problem; you should say what's happened, not what you think has gone wrong. Think "I crashed my car as the brake peddle didn't slow the vehicle down" rather than "I think my brake pads are worn".

Once you've done that you should provide the full logs. If you have some thoughts on which lines in the logs are most important then do explicitly mention them, but don't delete everything from the log apart from what you think is important. You are asking for help. You don't fully understand the system. You will cut important information out of the logs because you don't think it's relevant because you don't appreciate the full issue. If you did know enough about what was going on to know which log lines are relevant then you wouldn't need to ask for help!

So please, when asking for help, send full logs and describe what the issue is, don't just make guesses and provide incomplete information to someone who is trying to aid you.