From the NannyMUD documentation

LAST CHANGE

2000-12-16

NAME

        logger - Logging things to keep track of events in your area.

FUNCTIONS

OTHER FUNCTIONS

        detailed_log    For those who know what they are doing, exactly.
        logit           Works as in the old loggers.
        simple_log      Simple to use for logging kills.
        kill_hook       Easiest of all to use, are the hooks.
        die_hook
        get_parsed_data Gives the raw data.
        get_log         Gives processed data.
        query_last_time Gives when a log-entry was last done.
	clear_all_data	Removes all data saved so far.

DESCRIPTION

	INTRODUCTION
        This logging system allows for easy logging of events in your area,
        especially whom kills what and is killed. It can be used to log other
        things too, without much problem. The system have several features:

        + few file accesses (which keeps down the lag it generates).
        + data is cached (which causes fewer file accesses).
        + logging turns off if area is closed.
        + logging turns off if the wizard hasn't been on for long, and it
          does not start again just for him logging on 1 second.
        + log-files resides in your directory, but has some limits imposed.

	FORMAT
        The logg written by this logger is in a special format. Entries are
        indexed by a time-stamp and a counter. Every entry contains
        the information:

        TAG     Typically "died" or "kill".
        TIME    The time.
        LEVEL   The level of the living.
        NAME    The name of the living.
        GUILD   The guild of the living.
        ASSISTS A space-separated list of names of helpers. 

        You can cram whatever you want into those strings and ints, since in
        the end it is you who will have to build tables and such from the
        data, and you should then know what you have logged.

	HOW TO USE
        There are many ways in which the logger can be used, but most natural
        would be to inherit the logger and a creating a separate room that
        analyses and presents the material.

        The simple approach:
        1/ Copy the file /std/special/logger/logger_inherit.c to a good place
           in your directory structure.
        2/ Copy the file /std/special/logger/log_room.c to a good place in
           your directory structure.
        3/ Change the #define in the log-room to point at your own logger.
        4/ Add more code to the log-room to suit your own taste.

        As for logging, there are several ways of doing it. Most convinient in
        most cases, are the hooks as they can easily be added to monsters you
        clone:
        + for logging whom killed your monsters, just add a die-hook to it.
        + for logging whom your monsters killed, just add a kill-hook to it.

        For more control and in order of complexity, you can call simple_log(),
        logit() and detailed_log() from remote_real_monster_died() in your
        monster.

NOTE

        The logger will create a save file in your homedir named 'logger.o'
        which will hold all entries. The logger will occasionally remove
        entries: 
        1/ Entries older than 90 days will be removed.
        2/ At most 999 entries will be kept in the file. This corresponds
           heuristically to a 50k log-file of the traditional type. 

FUNCTION

NAME
        detailed_log - 


SYNTAX
        int detailed_log(string mess, int time, int lvl, string name,
                         string guild, string *assist)

DESCRIPTION
        This function allows you to log exactly what it is you want, mainly by
        feeding it already processed data. In order to keep things working, you
        HAVE to provide all the arguments, with correct types.




FUNCTION

NAME
        logit - 


SYNTAX
        int logit(string mess, mixed ob, object *assist)

DESCRIPTION
        This function is closely related to the only function available in the
        original loggers. The string 'mess' is the tag, usually "kill" or so,
        the 'ob' is the agent doing the deed, and 'assist' is an array of
        objects assisting in the deed. 


NOTE
        There are only two reasons why you would want to use this:
        1/ You're a masochist and like pain, or
        2/ You're not really logging kills.
        If you're none of the above, you most probably want to use the function
        simple_log().




FUNCTION

NAME
        simple_log - 


SYNTAX
        int simple_log(string mess, object monster)

DESCRIPTION
        This function is what you want to use. The logger then sorts out things
        like the killer, his level, guild, and assists.




FUNCTION

NAME
        kill_hook - 


SYNTAX
        void kill_hook(mixed array, object killer)

DESCRIPTION
        This is the function that will be called if you added a kill-hook
        to your monster. It will log things when your monster kills things,
        like players.




FUNCTION

NAME
        die_hook - 


SYNTAX
        void die_hook(mixed array, object victim)

DESCRIPTION
        This is the function that will be called if you added a die-hook
        to your monster. It will log things when your monster dies.




FUNCTION

NAME
        get_parsed_data - 


SYNTAX
        mapping get_parsed_data()

DESCRIPTION
        This function returns  acopy of the raw data. This is a mapping:

        ([ string TIME_KEY, ({ string TAG    ,
                               int    LEVEL  ,
                               string NAME   ,
                               string GUILD  ,
                               string ASSISTS }), 
           ...
        ])




FUNCTION

NAME
        get_log - 


SYNTAX
        mixed get_log()

DESCRIPTION
        Calling this function gives you an array of arrays. The format is:

        ({ ({ string TAG   , 
              int    TIME  ,
              int    LEVEL ,
              string NAME  ,
              string GUILD ,
              string ASSISTS }),
           ...
        })

        which should be easy enough to process into whatever presentation you
        wish for.




FUNCTION

NAME
        query_last_time  - 


SYNTAX
        int query_last_time()

DESCRIPTION
        This function gives you the time when a log-entry was last made.