The Xlogmaster Tutorial: ========================= Alright - since I hate writing documentation, I will try to keep this one as short as possible while giving you all the information you need. The Xlogmaster has been around since middle of 1996, but back then it was written with the xview toolkit and the configurability was compile-time only, so I never bothered to release it to anyone but good friends... the version you have on your harddisk now is fortunately a complete rewrite. ;-) ********************************************************************************** **** Important information for all those who are too impatient to read the full documentation (as I usually am): :-) RIGHT MOUSE BUTTON IN TEXT WINDOW BRINGS UP MENU !! ******** MIDDLE MOUSE BUTTON HIDES/SHOWS BUTTONS !!! ************ ********************************************************************************** SOME NOTES FOR THE BEGINNERS: --------------------------- Although the GTK+ feels a little clumsy sometimes (for instance you will notice that you have to click on a button and then move the mouse a little in order to be able to select it) and has it's little flaws it is already VERY nice and has a good chance of becoming one of the main toolkits, I'd say. Apart from how nice it is to write the menus and things like that let me just say this much: You should have a look at the "gtkrc" files... they basically allow you to freely modify the look of the xlogmaster to fit your needs / your desktop during runtime - if that isn't cool I don't know what is. USING XLOGMASTER: ---------------- The xlogmaster has basically 2 modes - both named after the UNIX program that performs a similar duty. The standard mode is obviously the: TAIL-Mode: This mode behaves like "tail -f", so it displays logfiles continuously (refreshing every "interval" seconds - default is 0.3, so you won't notice much of a delay there...). You can scroll back with the slider to have a look back in time. By the way: The scrollbar will always keep it's relative position towards the end, so if you set it 10 lines above the end it will stay there - I think this is the best way of handling it... but enough of this, let's continue with the CAT-Mode: This mode basically does a "cat" of the given file every "interval" seconds. At first this might seem weird, but it allows you to keep track of all those files & devices that put out stuff anew on every cat. You can for instance keep track of the /proc/ devices that are of interest for you, or anything else that works with the same principle. Extremely nice for us control freaks... * About the Filters: * ---------------- You can set a practically unlimited number of filters separately for every entry. Maintaining them is done via the menu (or config file - see below) and should be easy enough so I don't have to say too much about it. There is just a few things about the matching algorithms I'd like to say: The matching is done PER LINE, so no multi-line matches !! The Xlogmaster uses the real REGEX routines since version 1.4.2 - this means you can build incredibly powerful patterns (see GNU REGEX guide for help). The extended functionality since version 1.3.0 made it neccessay to divide the filters into two classes: CLASS0 - Filters: -------------- Class 0 filters are filters that are being applied during display-time. The CLASS0 Filters are excluding each other, only one can be chosen. There are three Class 0 filters: RAISE, LOWER & HIDE. RAISE: shows the matching line in a brighter color (see gtkrc). LOWER: shows the matchine line in a darker color (see gtkrc). HIDE: hides the matching line. If multiple filters match on one line the one with the highest priority is applied. The priorities (highest to lowest) are: HIDE, RAISE, LOWER. CLASS1 - Filters: -------------- Class 0 filters are applied during read-time and very often in the background. While Class 0 filters are (of course) only active if you view the logfile they have been defined for, Class 1 Filters are ALWAYS active and they are NOT excluding each other, you can define all of them on a single match if you want, the logfiles are being read in the background. There are four Class 1 filters: ALERT, NOTICE, UNICONIFY & EXECUTE. ALERT: Lets the button of the logfile that triggered the alert flash in a bright color (see commandline options) and then the button slowly fades back to normal (time and smoothness also controllable via commandline). This is for immediate points of interest, stuff that gets less interesting if you don't view it immediately. The fadeout not only gives you an idea of how old the alert was but it also prevents the buttons from being all read just because you've been away for a few hours. NOTICE: Pops up a little window at the current mouse position that displays when there has been an alert and which logfile had it. if you click on the entries you can see the line that triggered it. This is thought for extremely important things and stuff that you need to know even if you've been away for a week, so the notice box will stay there until you dismiss it. UNICONIFY: If you have limited space or just one desktop this is your option... whenever a matching line shows up in the logfile this filter has been defined for, the Xlogmaster deiconifies itself automatically. This means you can keep it iconified without having to fear you might miss anything. EXECUTE: Executes the given program basically just as typing it in in the shell would do - you also have some variables you can use: %F: absoute path to file/device of entry %H: helptext of entry %L: line that actually triggered the EXECUTE %M: mode of entry %N: name of the Logfile that triggered the EXECUTE additionally all the variables are also given as environment variables. They are called XLM_FILENAME ( = %F ) XLM_HELP ( = %H ) XLM_LINE ( = %L ) XLM_MODE ( = %M ) XLM_NAME ( = %N ) and can be used the usual way. A word of warning: Since the routine will NOT check for whether a line triggered the alert multiple times you should make sure your substring is kinda specific - otherwise you might get so "overinformed" that it gets very annoying ! :-) If you think about it you could even pipe the stdout of the xlogmaster into a logfile and create EXECUTE{echo XYZ} filters. That way you'd have a logfile that you can control with the Xlogmaster. *GRIN* Oh - and one last word: No piping in EXECUTE - at least not from the Xlogmasters side. You COULD do something like this though (example is for the bash ): /bin/sh -c "commandlineaslongasyouwantforyourfavoriteshell" And in there you could use piping and everything else... :-) If there are multiple matches on a line ALL of them are being taken. This means you could make the same string trigger all three actions... Audio Support: ----------- Since version 1.3.0 the Xlogmaster got Open Sound System (OSS) support. For every Class 1 filter category you can define a special sound that gets played whenever this category has been triggered. The sound files should be playably via "cat filename > /dev/dsp", so they should be about 8KHz and in a standard format (WAVE, ULaw or so). See manpage for commandline options concerning sound. Commandline Options: ------------------ please see the manpage Configuraton files: -------------- There are basically two different format: one for the logfiles to be watched and one for the style of the xlogmaster (the gtkrc files). I won't say anthing about the gtkrc ones - you can go to the GTK+ docs for that and I even supplied some examples in gtkrc-samples - some people might want to know about the format of the log-config files, though. They are pure ASCII and look like this: . . . MODE{FILENAME,INTERVAL,BUTTONTEXT,HELPTEXT} . . where: - MODE is either CAT or TAIL - FILENAME is an absolute filename - INTERVAL is the interval between two refreshes (in seconds/10) - BUTTONTEXT is the text on the button - HELPTEXT is the text to pop up when the mouse stays over the button for a while MODE,FILENAME, BUTTONTEXT are mandatory, INTERVAL & HELPTEXT are optional. You probably won't need to edit it by hand, though, because the menu allows you to create your configuration very nicely and then you can save it. If you want to edit the filter settings by hand, just add the filter entrys BELOW the logfile you want them to apply to. They are of the form . MODE{REGEXP} . where MODE is one of "RAISE", "LOWER", "HIDE", "NOTICE", "ALERT", "UNICONIFY", "EXECUTE", "INVERT", "CASE_SENSITIVE" and REGEXP is the string you want the filter to search for. You can also give a list of modes separated by commas, but only one of the Class 0 filters is allowed ! (so RAISE,NOTICE{regexp} would be o.k. whereas RAISE,LOWER isn't) If you specified EXECUTE there is another string appended behind the REGEXP (also in {}) - this line is identical to the one you can enter in the customisation menu. So an execution entry would look like: EXECUTE{match me}{/bin/program -option dostuff}. The "INVERT" and "CASE_SENSITIVE" flags are not filters but rather options for matching (whether the sense should be inverted and whether the matching should be done case sensitive) that can be used in conjunction with any filter. NOTE: IT IS CRUCIAL THAT THE FILTER ENTRY IS IN JUST ONE LINE, OTHERWISE READING IT WILL FAIL !!!! If you put a logfile configuration file to: "$(HOME)/.xlogmaster" it will automatically be read at startup. COPYING ------- The Xlogmaster a GTK+ based program to keep track of logfiles & devices Copyright (C) 1998 Georg C. F. Greve This is a GNU program This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Contact: mailto:xlogmaster-bugs@gnu.org http://www.gnu.org/software/xlogmaster/ Secondary sources: http://porter.desy.de/~greve/xlogmaster/ http://www.fusebox.hanse.de/xlogmaster/