
The datamonitor module is designed to allow GEAS to monitor data activities,
and dynamically adjust resource allocation and caching in order to maximimse
performance. Currently, it does very little of this  :)


The dm_event() method is used to report all activities on an object, such as
editing a field, reading a field, creating or deleting an object.

Currently, this function only calls logging functions, to allow a log to be
kept of all data access. (Note: if/when transactions are implemented, the
log will need to record enough information that the true sequence of events
is recorded - logging events that are subsequently rolled back would be a
bad thing.

In the future, GEAS will be able to have another thread running that will
watch events, and attempt to improve performance.


add_datamonitor_logfile()
-------------------------
This function adds a new file for storing log events. It accepts a bitmask
to indicate what events should be logged. Note that it is possible for a
single event to be logged in multiple files:

eg:
    File 1: DM_EVENT_OBJECT_NEW + DM_EVENT_OBJECT_DELETE
    File 2: DM_EVENT_OBJECT_NEW + DM_EVENT_FIELD_WRITE

All object creation events will be logged to both file 1 and file 2. Note
that moving an object to or from the database is not an event. (It may be
logged as a DM_EVENT_DATABASE event at some future time, however.)

Currently a log file can not be removed.


general
-------

Errors should not be logged as the event that should have occured. For
example, attempting to create a non-existant class should be logged as an
error.

The DM_EVENT_SECURITY type is intended for noting activities that were
prevented by the security system. Passwords and other information read from
business objects should never be entered into the log.

EG: If a user attempted to write to a field that they only have read access
for, then the log should indicate the userid, transactionid, classname,
object, and type of security error (write access denied).


dm_event()
----------

This function takes as arguments the username, a transaction ID, and an
event type. Additional arguments depend on the event type, and provide
additional information for the log.

The username and/or transaction ID may be NULL, in which case no data will
be recorded. Username should, in most cases, not be NULL.

The transaction ID will be important once transactions are implemented, as
it will be required in order to process the logs to determine exactly what
occoured.


dm_logentry()
-------------

This function acts like printf(), but writes information to all appropriate
log files, along with additional information on the event being logged.

It takes a printf() style format string, allowing arbitrary information to
be noted in the log.

dm_vlogentry()
--------------

This acts like dm_logentry(), but accepts a va_list pointer. This was
created to allow other functions with printf() style semantics to easily
also log the message.

It takes a printf() style format string, allowing arbitrary information to
be noted in the log.



The following constants are #define'd to represent all known messages. 


dm_event() event types:
-----------------------
DM_EVENT_OBJECT_NEW       : Classname ObjectID
DM_EVENT_OBJECT_DELETE    : Classname ObjectID
DM_EVENT_FIELD_WRITE      : Classname ObjectID Field Value
DM_EVENT_FIELD_READ       : Classname ObjectID Field
DM_TRANSACTION_BEGIN      : <no extra information>
DM_TRANSACTION_COMMIT     : <no extra information>
DM_TRANSACTION_ROLLBACK   : <no extra information>
DM_TRANSACTION_CHECKPOINT : <no extra information>


dm_logentry() or dm_vlogentry() event types:
--------------------------------------------
DM_EVENT_SECURITY_LOGON_SUCCESS
DM_EVENT_SECURITY_LOGON_FAIL
DM_EVENT_SECURITY
DM_EVENT_ERROR
DM_EVENT_WARNING
DM_EVENT_MESSAGE
DM_EVENT_DATABASE


Future issues
-------------

Log entries are currently written to a file, and the file is then closed.
Each new entry requires opening the file (for append), writing the data, and
then closing it again. Write-once technologies may be important, and this
code may need to be enhanced to ensure a permanent record of an event is
made on appropriate media. Performance issues may also be important with
very large log files.

