From the NannyMUD documentation
2000-12-16
simple_logger - Logging things to keep track of events in your area.
log
simple_log
detailed_log
INTRODUCTION
The simple_logger allows you to log things in a neat and convenient
fashion. It caches disk accesses, and thus reduces lag, and this is
one of the most important reasons why you should use it. It also stops
logging if the owner's area is closed or the owner turns inactive.
It furthermore limits log files from growing indefinitely.
HOW IT WORKS
The simple_logger saves the log entries in a file called
simple_logger.o which resides in your ~ dir. The log entries are not
saved in an easy-to-read format - this is to allow maximum flexibility
for the user in creating his or her own views of the logged data.
Instead of reading the file directly, a good look at the logs can be
gotten by simply examining the logger. For more information about
exactly how this internal save format works, read the extensive code
comments in the simple_logger.c source file.
HOW TO USE
1) Make a file in your dir which contains this single line of code:
inherit "/std/special/logger/simple_logger";
2) In the objects you want to log something, have a #define:
#define LOGGER load_object("/players/yourname/path/simple_logger")
either directly or via a header (.h) file.
3) To log something, simply do
LOGGER->log("name_of_log",
"a text describing what happened",
ob);
...where we assume that 'ob' is the player/monster who should be
logged as the one to make something happen (see above).
4) If you desire other ways to view the log data, get creative. You
can add new commands in init() with add_action, and add your own
functions for composing exactly the view you want. For everyday
purposes, the default view (the one you see with the 'viewlog'
command) should suffice, however.
A more extensive example: Suppose you have a monster, say a dwarf,
and you want to know when it's killed and by whom. Then a die_hook
is the perfect thing to use. Have this code in your dwarf's reset():
add_hook("die_hook", this_object());
...and then have this function in your monster (assuming LOGGER is a
#define pointing to your logger as explained above):
die_hook(data, who) {
// data[0] contains the killer object if any.
LOGGER->log("kills", "killed dwarf", data[0]);
}
This idea can be generalized to most any case... Use a kill_hook to
log when your monsters kill someone, log in init() in the first room
in your area to find out when someone enters the area (watch out, such
a log tends to grow _fast_!), and so on.
There are a few limitations imposed on the logger. The reason for this is to save memory and disk space. They are: 1) You can only have 10 different logs. 2) Each log name can only contain 400 entries. 3) Entries older than 90 days will be removed. 4) Logging will be turned off if your area closes. 5) Logging will be turned off if you haven't logged on for 30 days. If you try to have more than 10 logs, the logging will simply fail. If one of your logs contain more than 400 entries, the oldest entry will be removed to make room for the new one.
NAME
simple_log -SYNTAX
varargs status simple_log(string log_name, object who)DESCRIPTION
Use this function when you want to log the time, someone's name, guild and level only. If the second argument 'who' isn't given, this_player() is used by default.
FUNCTION
NAME
log -SYNTAX
varargs status log(string log_name, string log_text, object who)DESCRIPTION
This is the function to use in most everyday logging situations. It will log the time, someone's name, a string telling what happened, as well as the guild and level of the person who made something happen. If the argument 'who' isn't given, this_player() will be used as a default.
FUNCTION
NAME
detailed_log -SYNTAX
varargs status detailed_log(string log_name, string log_text, object who, mixed others)DESCRIPTION
Use this function when you want to, apart from the info logged with 'log()' above, also want to log a list of things - the 'others' argument can be an array of either objects or strings, and the names of the objects or the strings will be appended to the log. A case where this could be useful is for example to log all the attackers of a monster, as opposed to just the player who struck the killing blow.
FUNCTION
NAME
purge_data -SYNTAX
varargs status purge_data(string which_log)DESCRIPTION
Calling this function without an argument removes _all_ logs. If a log name is given as an argument, only that particular log is removed. If the log wasn't removed, 0 is returned, otherwise 1 is returned.NOTE
Only the simple_logger's owner or a level 30++ is allowed to use this function to clear log data.
FUNCTION
NAME
query_log_data -SYNTAX
mapping query_log_data()DESCRIPTION
This function returns a copy of the raw log data, as kept in the save file simple_logger.o. The data is stored in a mapping indexed with log names, like this: ([ string log_name1:({ int time, string log_text, string name, int level, string guild, string others }), string log_name2:({ int time, string log_text, string name, int level, string guild, string others }), ,,, ]) This information is probably mostly useful for debugging, or for creating your own views of the log data.
FUNCTION
NAME
query_log -SYNTAX
mixed query_log(string log_name)DESCRIPTION
This function returns an array containing the entries of a certain log, if a log by the name log_name exists in the logger. The format is ({ ({ int time, string log_text, string name, int level, string guild, string others }), ({ int time2, string log_text2, string name2, int level2, string guild2, string others2 }), ... }) Again this is mostly useful for creating your own log data views.