nteventlog

MODULE

nteventlog

MODULE SUMMARY

This module implements a generic interface to the WIndows NT event log. The module is specific to Windows NT and in some ways replace the os_sup module, which is highly Unix specific.

DESCRIPTION

The nteventlog module is a server which will inform your erlang application of all events written to the Windows NT event log. This is implemented with a port program that monitors the eventlog file and reacts whenever a new record is written to the log.

Your erlang application is informed of each record in the eventlog through a user supplied callback function (an "MFA"). This function can do whatever filtering and formatting is necessary and then deploy any type of logging suitable for your application. When the user supplied function returns, the log record is regarded as accepted and the port program updates it's persistent state so that the same event will not be sent again (as long ar the server is started with the same identifier).

When the service is started, all events that arrived to the eventlog since the last accepted message (for the current identifier) are sent to the user supplied function. This can make your application aware of operating system problems that arise when your application is not running (like the problem that made it stop the last time). The interpretation of the log records is entierly up to the application.

When starting the service, a identifier is supplied, which should be reused whenever the same application (or node) wants to start the server. The identifier is the key for the persistent state telling the server which events are delivered to your application. As long as the same identifier is used, the same eventlog record will not be sent to erlang more than once (with the exception of when grave system failures arise, in which case the last records written before the failure may be sent to erlang more again after reboot).

If the event log is configured to wrap around automatically, records that has arrived to the log and been overwritten when the server was not running are lost. The server however detects this state and loses no records that are not overwritten.

EXPORTS

start(Identifier,MFA) -> Result

Types:
Identifier = string() | atom()
MFA = {Mod, Func, Args}
Mod = atom()
Func = atom()
Args = list()
Result = {ok, Pid} | {error, {already_started, Pid}}

LogData = {Time,Category,Facility,Severity,Message}
Time = {MegaSecs, Secs, Microsecs}
MegaSecs = integer()
Secs = integer()
Microsecs = integer()
Category = string()
Facility = string()
Severity = string()
Message = string()

This function starts the server. The supplied function should take at least one argument of type LogData, optionally followed by the arguments supplied in Args.

The LogData tuple contains:

1. The message Time is represented as by the erlang:now() bif.
2. The message Category which usually is one of the strings "System", "Application" or "Security". Note that the NT eventlog viewer has another notion of category, which in most cases is totally meaningless and therefor not imported into erlang. What this module calls a category is one of the main three types of events occuring in a normal NT system.
3. The message Facility is the source of the event, usually the name of the application that generated it. This could be almost any string. When matching events from certain applications, the version number of the application may have to be accounted for. What this module calls facility, the NT event viewer calls "source".
4. The message Severity is one of the strings "Error", "Warning", "Informational", "Audit_Success", "Audit_Faulure" or, in case of a currently unknown Windows NT version "Severity_Unknown".
5. The Message string is formatted exactly as it would be in the NT eventlog viewer. Binary data is not imported into erlang.

start_link(Identifier,MFA) -> Result

Types:
Identifier = string() | atom()
MFA = {Mod, Func, Args}
Mod = atom()
Func = atom()
Args = list()
Result = {ok, Pid} | {error, {already_started, Pid}}

Behaves as start/2 but also links the server.

stop() -> Result

Types:
Result = stopped

Stops a started server, usually only used during development. The server does not have to be shut down gracefully to maintain its state.

SEE ALSO

os_sup(3) and the Windows NT documentation.

AUTHORS

Patrik Nyblom - support@erlang.se