@database GuruLog.guide
@author Kyzer/CSG
@$VER: GuruLog.guide 1.1 (03.04.98)
@remark you can read this in a text viewer, if you need to.

@node main "GuruLog v1.1 documentation"

@{u}GuruLog v1.1@{uu}

 @{"  " link intro} Introduction
 @{"  " link usage} Using GuruLog
 @{"  " link alertd} Using alertd
 @{"  " link options} GuruLog options
 @{"  " link history} GuruLog history
 @{"  " link credits} Credits

GuruLog is a program to identify and keep a log of software failures.
Copyright (C) 1997  Kyzer/CSG

alertd is a program to invoke GuruLog automatically after Recoverable
Alerts. Copyright (C) 1997  Kyzer/CSG

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.

@{"Contacting the author" link credits}
@endnode

@node intro "Introduction"
A  few  months  ago,  a program called 'GuruStatistix', by Steffen Clemenz,
caught  my  eye.  It gave statistics on your Amiga's most common deaths and
failures.

But!  It  turned  out  that  it  only  worked on special logfiles that were
already  created,  by the MCP program. Which is an evil piece of scum. So I
wrote my own version.

This  software  package comes in two parts: the main GuruLog program, which
identifies  and  logs  software failures, and a small 'alertd' patch, which
runs  GuruLog  every  time  a Recoverable Alert occurs while your system is
running.

@{"How to use GuruLog." link usage}
@endnode

@node usage "Using GuruLog"
GuruLog requires Workbench 2 or better to run.

GuruLog is not meant to be an 'interactive' tool. It is for running in your
computer's startup. If it is working properly you should never see it until
you want to look at the log it creates.

@{"Installing GuruLog" link install}

@{"Using GuruLog with GuruStatistix" link gurustatistix}

@{"GuruLog options" link options}
@endnode

@node install "Installing GuruLog"
GuruLog  should  be run before any 'major' startup programs and patches, it
is best run just after SetPatch in the startup-sequence.

The  suggested  installation  is  to  copy  the program files 'GuruLog' and
'alertd'  to  your  C:  directory, and the data file 'gurus.dat' to your S:
directory. Then add these two lines to your 'S:startup-sequence', after the
'SetPatch' line:

c:GuruLog S:gurus.log S:gurus.dat TASKNAME NOUNKNOWN
Run <>NIL: c:alertd c:GuruLog S:gurus.log S:gurus.dat TASKNAME

A log of your system's gurus will be held in S:gurus.log

Please read the information about the @{"TASKNAME" link TASKNAME} option, to see if you really
should  be  using  this option, and if you need to move the position in the
startup-sequence where you run GuruLog.
@endnode

@node alertd "Using alertd"
alertd is a @{"daemon" link daemons}, and should be run sometime during startup.

The entire command line given to alertd is executed as a command after
every alert. As alertd does not 'auto-detach', you must RUN the program.

Basically, use this as a template:

Run <>NIL: c:alertd c:GuruLog <GuruLog options>

You can remove alertd by sending it a CTRL-C with the break command,
or simply run alertd again from the shell.

Remark at how small alertd is - under 400 bytes.

NOTE: alertd is not entirely 'pure' - never make it resident.
@endnode

@node daemons "Daemons (and not Hill, either)"
  "In  the  UNIX  world, the term _daemon_ is somethings used to refer to a
server. usually, it means that the server is 'permanently available', which
implies  [...]  that  it  is  started  at  boot-time. Also, daemons usually
provide  a 'system-related' service [...] many servers have names ending in
'd' in honour of the name."
  - Chris Brown, "UNIX: Distributed Programming"

alertd  is  a  'system-related'  server.  It  executes  a  specific command
whenever  a  user program calls Alert(). It should be started at boot time,
and remain running for the whole uptime of the computer.

Incidentally, 'daemon' supposedly means 'Disk And Execution MONitor'...
@endnode

@node options "GuruLog options"
You may set how GuruLog operates using the following options.

GuruLog LOGFILE/A, GURUDAT, TASKNAME/S, NOUNKNOWN/S

for example:

GuruLog S:gurus.log S:gurus.dat TASKNAME NOUNKNOWN

@{"  " link LOGFILE} LOGFILE
@{"  " link GURUDAT} GURUDAT
@{"  " link TASKNAME} TASKNAME
@{"  " link NOUNKNOWN} NOUNKNOWN
@endnode

@node LOGFILE "LOGFILE option"
LOGFILE/A

GuruLog  requires  the name of a file to write the log to. If the file does
not  already  exist,  GuruLog will create it. This file will be appended to
each  time  GuruLog  is  run,  provided  -  of  course  -  that a 'guru' or
recoverable alert has recently occurred.

The log entries take this format:

Date  : Monday 19-Jan-98  22:17:41
Task  : 002247A0 "Unknown"
Error : 0100000C (Recoverable)
By    : exec.library
Cause : Sanity check on memory list failed during AvailMem(MEMF_LARGEST)

The  log  is processable by the excellent GuruStatistix program, which will
allow  you  to see your Amiga's most common failures - and, usefully, which
programs are most commonly failing.
@endnode

@node GURUDAT "GURUDAT option"
GURUDAT

Those  cryptic  guru  error  numbers can be decoded using a 'gurudat' file,
specified  on  the  commandline.  One  is  provided  for  your use with the
package, called 'gurus.dat' - feel free to add to error lists in this file.

@{"The format of the gurus.dat file" link gurudat_format}
@endnode

@node gurudat_format "The format of the gurus.dat file"
The file is read in line by line, any line that does not fit the format
will be ignored.

The format, per line, is as follows:

- an 8-digit code number (hexadecimal). Must be a full 8 digits.
- one single space
- the description for that code number.
 
The code number can refer to:
- a failure or guru code: all 8 digits are used  (XXXXXXXX)
- an error subsystem, last 6 digits must be 0    (XX000000)
- a 'general' error, used when no specific error (00XX0000)
- another part of the 'general' errorcode        (0000XXXX)

examples:
0700000E A filehandle was closed more than once
01000000 exec.library
00050000 OpenResource
00008020 cia.resource

The  last two 'general' descripions are put together when a specific reason
for  the  alert  cannot  be  found. For example, the code for 'exec.library
cannot  open  cia.resource'  would  be 01058020, you can see from above how
these are combined.

The log entry in that case would look like so:

Error : 01058020 (Recoverable)
By    : exec.library
Cause : OpenResource cia.resource
@endnode

@node TASKNAME "TASKNAME option"
TASKNAME/S

This is a bit naughty, but useful. Basically, it takes the 'task' value you
see  in  the  flashing  alerts, and trys to find out the name of this task.
@{b}This shows you which program caused the crash/alert.@{ub}

However,  it  may well be useless, and if you run the program 'Enforcer' or
'CyberGuard', you will certainly get hits.

That  is why you have to enable this task-name-finding mission by including
this  option.  If you do not enable the option, no Enforcer hits occur, and
the task name will always be recorded in the log as 'Unknown'.

The  method  I  use regularly checks that where it is looking is in 'valid'
memory.  Therefore,  @{b}if you have memory that is not autoconfig@{ub} and requires
to  be  'enabled'  with a command, you should always run that command first
before running GuruLog.

If  you  have  memory that empties its contents on reset, you will only get
the 'unknown', for obvious reasons.
@endnode

@node NOUNKNOWN "NOUNKNOWN option"
NOUNKNOWN/S

After  using  GuruLog 1.0, I discovered that my when I booted for the first
time  since  switching  the  power  on,  I  occasionally  got  very  random
gurucodes,  like  51155455  task  BFAAAAAE.  These  were  not gurus, yet my
program  was  trying  to  explain  them  and  log them anyways. I could not
specifically tell GuruLog which gurucodes to ignore, because this gurucode
was random.

So,  instead,  I  came  up  with  the idea: "If GuruLog has read the entire
gurudat  file,  and it cannot explain the gurucode, it should ignore it and
quit without recording this gurucode in the log."

I add this as a switch, mainly so you can switch this behaviour on with the
boot-time run of GuruLog, but leave it off with the alertd-started runs of
GuruLog, as you do not get 'spurious' alerts.

If the gurudat file is not specified or cannot be loaded, this option does
not come into effect.
@endnode

@node GuruStatistix
GuruStatistix by Steffen Clemenz

@{B}AMINET: util/misc/GuruStatistix.lha @{UB}

@{B}WWW: http://userpages.fu-berlin.de/~clemenz @{UB}

It's very simple to set GuruStatistix to use GuruLog's files instead of the
default  MCP  settings. Just install it as usual, except the 'Gurudat' file
becomes  S:Gurus.dat,  and  the  'GuruHistory' file becomes S:Gurus.log, or
whatever you have installed those files as.
@endnode

@node history "GuruLog history"
0.x:	Initial development (12.01.98)
	Stopped using super-slow ReadStr() and Val().
	Describes compound errors reasonably well.
	Wrote alertd.

1.0:	First public release (31.01.98)
	Made alertd a bit more sensitive while unpatching.
	Use cut-down version (<200 bytes) of stealchip
	Rewrote alertd to use CreateMsgPort() - smaller now.
	Tidied up docs. Included clr.asm and hex.asm sources.

1.1:	Second release (03.04.98)
	El-disastro - alertd.asm disappeared from distribution and my HD -
	had to rewrite. Rewrote in slightly safer and more commented manner.
	Added @{"NOUNKNOWN" link NOUNKNOWN} option.
	Nicer date creation code (now an object).
	Stronger & nicer description code.
	Nicer and shorter taskname grabber.
	Stopped using StringF() and WriteF(). Now slightly shorter.
	Flattened almost all code.
	Added 'daemons' node to guide, moved gurudat format into new node.

@{" Future development " link future}
@endnode

@node future "Future prospects for GuruLog"
- None planned.

Any further suggestions from you are very welcome, as are extra entries for
the gurus.dat datafile. @{"Contact me." link credits}
@endnode

@node credits "Credits"
GuruLog was created by Kyzer/CSG using E v3.3a by Wouter van Oortmerssen.
alertd was created by Kyzer/CSG using PhxAss v4.37 by Frank Wille.

With thanks to Steffen Clemenz, Thomas Richter, and Ben Hutchings.

GuruLog  prints  log  data in the format sent to me by Steffen Clemenz, its
only  intent  is  to  remain  parsable by the GuruStatistix program. I have
never  bothered  downloading  or  installing MCP. GuruLog is not, and never
will  be,  based  on  code  from MCP or ALiENDESiGN. I acknowledge that the
concept of GuruLog is based on MCP's 'GuruHistory' feature.

Contact:

Kyzer/CSG,
49 Fairview Road,
AB22 8ZG, Scotland.

or email: kyzer@4u.net

Incitement Works plc, http://www.abdn.ac.uk/~u13sac/
@endnode