Analyzing logs is usually cumbersome. It takes you away from coding and forces you to skim through hundreds of thousands of log lines to find out what caused that pesky bug to one of your customers who lives hundreds of miles away.
Delving into a log is no pretty picture. To get to the bottom of an issue sometimes requires a collaborative effort. You will want to have a tool that allows for several people to make notes and reply to notes on a specific log. Meet LogWizard - that's one of its features!
I created LogWizard to help anyone that really needs to analyze logs in order to hunt down bugs and/or issues that happen somewhere else (for instance, on the customer's machine).
I have written about how to use it in a different article, and more articles are about to come. For the purpose of this article, it's all about Notes.
As you will see, writing and repling to Notes is extremely easy. I created it that way, because unless it's dead easy, you won't use it - I wouldn't use it if it wasn't a breeze!
- Notes just for yourself - you might simply use it for yourself. Perhaps you're analyzing a very complicated log in several sessions - you might need to come back to it in a few days, and pick up where you left off.
- Sharing with colleagues - you and your colleagues can each create notes. You can reply to existing notes from your colleagues and/or delete notes.
- Sharing with Customer Support - You can have Customer Support take a look at the logs first and they can share their findings with you and the team. This will save you from the minutiae from dealing with common problems - which they should be able to identify. Or, at the very least, they can share with you their opinions as to what the issue is.
- Sharing with The Customer - you can share your findings with the customer. For instance, say AERO has to be turned on in order for your program to run corectly, but from your log, it's clear that this is not the case for your customer. Just add a note to the line that specifies AERO is off, something like "Please turn on AERO in order for XYZ to work correctly".
Sharing information with the Customer, when done correctly, can be a very powerful thing. You can do it in two ways:
- Just exporting the Notes. They will be exported in a nice .html file
- Exporting the Notes and the Log. They will be able to see the log exactly as you see it, together with notes. This speaks volues when it comes to being transparent with your customers. Probably you will seldom have to do this - since there will be a lot of information the customer is not interested in. But, if he requests it, why not?
Just in case you want to play a bit with this, I've provided some sample logs. You will find them in %appdata%\LogWizard\Samples. You can drag one onto LogWizard, show the Notes Pane (Alt-N), and then add/edit notes as it pleases you.
Before I go further: at the core of LogWizard is the View. A View is composed of several filters, allowing you to focus on a specific issue at a time.
Each Note that you make relates to a line from a specific View. Or, it's a reply to an existing Note.
Replies are nicely formatted so that you visually see who's replying to what.
Creating notes is as simple as can be:
1. Navigate to the line where you want to add a note2a. Either right-click on the line, select Note >> Create Note On This Line, or2b. Make sure Notes Pane is ON (if it's not, turn it on using Alt-N). Press Tab until you get to the edit box on the bottom-left. Depending on your visible pages, this will be one or two Tab keys. 3. Type your note, and press Enter. That's all!
As you naviate through the log, you'll see that the Notes Pane is in sync with your current line and view.
After you create a note, you'll see that at Line column, it will write your author initials. By default, I find the author name + initials (that identify you, in the notes) by looking at your Windows username. In case you want to change them, just go to Preferences (Ctrl-P), Notes tab, and change them as it pleases you.
So, you've made your first few notes. Yohoo! Now you want to share this with someone else (for instance, email it to your colleagues), click on Export on the bottom. Select Export Log + Notes (to .LogWizard file).
LogWizard will create two files, one that ends in .long.LogWizard, and one that ends in .short.LogWizard, and automatically opens them Windows explorer. The .long.LogWizard file is selected:
- the
.long file contains the log + the notes you've made, and - the
.short file contains only the notes.
When you share your log and notes between colleagues, you need to share the .long file with someone only once - when they open it, they will have the log file locally.
After that, you only need to share the .short file, which contains your latest notes - as someone opens it, it will automatically merge the notes.
As I've shown above, the first person to comment on the log will create a .long.LogWizard file. Assuming that is you, you will then share it with the rest of the team.
It does not really matter if you made any notes at the moment you shared the .long.LogWizard file. Whatever notes you've made before and after, are automatically merged with your colleagues.
Anyone who wants to look at the log will double-click the .long.LogWizard file - this will open the log (with LogWizard), together with your inital notes (if any) and they can start making notes.
Once you have made some meaningful notes, you will want to share them with your colleagues. Thus, you click Export, select Export Log + Notes..., select the .short.LogWizard file, and share it (email it, or your sharing tool of choice). Your colleagues will do the same.
To see what notes one of your colleagues made, open the .short.LogWizard file they send you. That's it - merging is automatically done. In case there's anything new, the Notes Pane will automatically open, and new lines are shown in a darker background.
If you realize a note is not useful (or has been superseded by another note), you can just delete it. This will remove clutter - the idea is to always be able to focus on what's important. If you see that someone else's note is not relevant anymore, you can:
- Reply to that note, explaining why the note is not relevant anymore
- In addition to that, you can delete the original note (which will delete yours too - but that's ok, see below).
To delete a note, just select the note (in the upper-left pane), and press DEL.
Deleting a note never really deletes it. I wanted to create an easy way to share information, and when it comes to notes, what you need to remember is that you won't need that many notes on a log. Perhaps if it's a very difficult log, you may need to enter 150-200 notes. That's nothing when it comes to storage.
Thus, I never truly delete notes. This brings another very important side-effect. There's no need for Undo. You deleted a note by mistake? No worries - just check the Show Del Notes, re-select it, and click DEL again - it will undelete it.
When it comes to deleting notes, anyone can delete anything: it's about trusting your colleagues - someone would not delete something without a good reason.
Once you and your colleagues have analyzed a log, you can pass the notes to your Customer Support. If it was a bug, you and your colleagues will decide when/if to fix it. If it was a misconfiguration problem at on the customer's machine, Customer Support can choose to export those notes and eventually provide more details.
Exporting the Notes is very powerful - the customer can actually see the original line that led to each comment from you guys - and if he truly wants, he can double check them with the original logs he sent you.
One very important thing to note is that the export takes into account the value of Show Del Lines - if that is checked, deleted lines will be exported as well. If you're exporting for your customer, you will likely want to uncheck that.
Also, Customer Support can check each comment for language - therefore, check your language when speaking. It might arrive at the customer! Customer Support can further delete some lines and finally, send them to the customer as a nice .html file.
The customer, when there's problem/bug, will send the logs to Customer Support. They can forward you the logs or create a bug in jira (or something similar), attach the logs and forward you the link to the bug.
You can also train them to look at the logs, and spot:
- common scenarios
- out of the ordinary scenarios
For a common scenario, they can actually solve it without bothering you at all. Spotting an out of the ordinary scenario comes with experience. Once Customer Support will have looked at enough logs, they will instinctively spot something out of the ordinary (and let you know about it, via creating some notes on the lines they think are the culprit). And if they guess wrong, that is still ok - you can just let them know that the issue they thought was out-of-the-ordinary is in fact not so.
After analyzing a log, you can also share your findings (i.e., notes) with Customer Support. In case this was a misconfiguration problem on the customer's machine, they can then learn about it (where it occurs in the log) and later on spot the same issue at other customers.
Training Customer Support does not have to be difficult. You just have to make it easy for them to find common scenarios - when viewing a log file. This means creating Views that are tailored for them. You can create a View that will contain most common scenarios - they would look at it, and see if they spot something. For instance, the easiest View would be one with Warnings, Errors, Fatal Errors, more or less like this:
As I've said before, at the core of LogWizard is the concept of a View - which is a collection of filters. Creating Views is beyong the scope of this article - just read this for more details.
When it comes to viewing a log, you and your colleagues can have different Views on it: you can create your own views - to focus on what is important to you at this specific time, and they can create their own - to focus on their task(s).
Just remember that each note relates to a line and a View. If you don't have the View someone created a note on, LogWizard will automatically open the Full Log pane (which shows the full log, without any filters on it) and select the line.
Most of the time you will want to have your Views in sync with your colleagues (or at least, the common ones). There are several ways to achieve this:
Have someone on your team create all the Views, and share them with the rest of the team
- Open any log from your application.
- Create the Views. Read this
- Share The Template (see below)
You can easily share Views and/or Templates (the Template is the collection of all Views for a log).
To share the Template
- Open the Source Pane (
Alt-O) - Click on
ToC. This will copy the Template to clipboard. - You can send the clipboard contents to someone else.
To use someone else's shared Template
- You need to have it copied into clipboard
- Open the Source Pane (
Alt-O) - Select the Template you want to copy it into (or simply create a new Template)
- Click on
FromC. This will paste the Template from clipboard.
To share a View:
- Select its corresponding tab.
- Open the Filters Pane (
Alt-F). - Click on
ToC. This will copy the View to clipboard. - You can send the clipboard contents to someone else.
To use someone else's shared View
- You need to have it copied into clipboard
- Select the View you want to copy it into (or simply create a new View)
- Open the Filters Pane (
Alt-F) - Click on
From. This will paste the View from clipboard.
Once you have the right Template for your log, you can further tweak it - modify the Views and/or create new Views that match what you're working on right now. That is totally ok - if for a note, LogWizard can't find the View, it will just open Full Log pane and show you the line the note is for.
By default, when you open a .LogWizard file, LogWizard will look for the Template corresponding to this log:
- If it finds it locally, it will use it. Thus, by default, it will always use your Template.
- If it does not find it, it will use the one from the
.LogWizard file. Every time you export to a .LogWizard file, we will also export your Template. This way, anyone opening a .LogWizard file will see the Template (containing all the Views) of the person that did the export.
Just in case you have a Template corresponding to this log, but want to see the Template from the colleague that exported the notes just hold SHIFT key when drag-and-dropping the .LogWizard file.
When you open a .LogWizard file, I need to find out the log it relates to and if you already have it locally. The latter part is not that important, since I could just re-copy the log locally.
However, the reason for uniquely identifying the log is to be able to automatically merge your notes (if any) with the notes from the .LogWizard file you're opening.
I have two methods for uniquely identifying a log file:
Fast: read 16Kbytes from beginning + 16Kbytes from end + include file size, and generate a md5 hash100% Accurate: generate an md5 hash of the whole file.
You will probably be ok with the Fast algorithm, but just in case you want accurate for sure, use the other method (which is of course, much slower, especially for large logs). To edit this, go to Preferences (Ctrl-P), Notes tab, and change it there.
History
- Oct 14, 2015 - initial version
