Log it or lose it

Log events to the Windows NT Event Log with JNI

By Sunil Kumar and Nitin Nanda, JavaWorld.com, 09/28/01

However, the JDK does not directly support writing to the NT Event Log. To do so, you need to expose a method in the JNI (Java Native Interface) DLL (Dynamic Link Library) to direct the events to the NT event viewer.

This article has three sections. The first covers logfiles, event sources, event categories, event identifiers, and event messages. The second section demonstrates how to create a message file as a DLL, how to make the DLL self-registering, and how to create a JNI DLL that exposes a method to direct events to the NT Event Log. Finally, you'll see a sample Java program illustrating the JNI method in action.

Note: The discussion in this article applies to Windows NT version 4.0 and higher.

The event logging mechanism

The NT Event Log, a Windows NT service that starts whenever Windows NT boots, logs warnings, exceptional conditions, and other administrative messages, all of which it writes to event logfiles. Since the service uses RPC (Remote Procedure Call), you can view and log the messages from remote machines.

You can employ event logging to:

• Catch exceptional conditions and log them for support staff.
• Read invalid values.
• Synchronize the sequence of applications by using the NT Event Log as a central facility. By logging the source name and time, the applications can check the events and start them in the correct order.

Applications report events by calling the ReportEvent() function. The system passes the parameters to the event logging service, which uses the information to write the event log record to the event logfile. Figure 1 illustrates the process.

The major elements used in event logging include:

• Logfiles
• Event sources
• Event categories
• Event identifiers
• Event messages

Let's examine each in turn.

Logfiles

The event logging service uses information from the EventLog registry key when an application writes to and reads from the Event Log. The EventLog key (shown in the following example) contains several subkeys, called logfiles. The logfiles allow the event logging service to locate the resource for a particular application to enable it to perform logging services. The default logfiles are Application, Security, and System. The structure in the registry is as follows:

HKEY_LOCAL_MACHINE 
    SYSTEM 
     CurrentControlSet 
       Services 
        EventLog
          Application 
          Security 
          System 

Applications and services use the Application logfile, while device drivers use the System logfile. When you turn auditing on, the system generates success and failure audit events in the Security log.

Event sources

Each logfile contains subkeys called event sources -- the name of the software that logs the event. The structure is as follows:

HKEY_LOCAL_MACHINE 
    SYSTEM 
     CurrentControlSet 
       Services 
         EventLog 
            Application
              AppName
            Security 
            System
              DriverName

Each event source contains information specific to the software that will log the events, such as the message files, as shown in the table below.

Event categories

Event categories help you organize events so event viewers can filter them. Each event source defines its own numbered categories and the text strings to which they are mapped. For example, in a data-intensive application, events could be: data write error, data read error, SQL error, and so on. Events would then fall under these categories.

Event identifiers

Event identifiers uniquely identify a particular event. Each event source can define its own numbered events and the description strings to which they are mapped. Event viewers can present these strings to the user.

Event messages

The event messages reside in message resource files containing parameterized strings. When the event message is written to the Event Log, it does not store the entire message string, but rather just the inserted values passed as parameters. The Event Log uses the event identifier to map to the event message displayed in the event viewer. There are two benefits to this arrangement:

• Most of the descriptive text can be stored in the resource file, thus decreasing the size of the logfiles
• The message strings can be made specific to the locale, enabling you to provide a separate resource file for each locale, thus making the application locale independent

Each event source registers message files that contain description strings for each event category and event identifier. These files become registered in the EventMessageFile and CategoryMessageFile registry values for the event source. You can create one message file containing descriptions for the event identifiers and categories, or create two separate message files. Keep in mind that several applications can share the same message file. You should typically create message files as DLLs.

Use the Event Log

So, how do you read and view the NT Event Log?

An event viewer application employs the OpenEventLog function to open the Event Log for reading events. The event viewer can then use the ReadEventLog function to read event records from the log. Figure 2 illustrates the process.

When the user starts the event viewer to view the Event Log entries, the event viewer calls the ReadEventLog() function to obtain the Event Log records. The event viewer uses the event source and event identifier to retrieve the message text for each event from the registered message file (indicated by the EventMessageFile registry value for the source). The EventMessageFile registry key contains the path of the message DLL. The event viewer uses the LoadLibraryEx() function to load the message file. The event viewer then employs the FormatMessage() function to retrieve the description string from the loaded module.

Free Download - 5 Minute Product Review. When slow equals Off: Manage the complexity of Web applications - Symphoniq

Free Download - 5 Minute Product Review. Realize the benefits of real user monitoring in less than an hour. - Symphoniq