Log4JNA Configuration

Log4JNA uses some configuration parameters to set up values in WindowsTM Registry that are required in order to write to the Event Viewer, all other Log4j 2TM values are used as described in the Log4j 2TM Configuration Guide

Note: WindowsTM requires Administrator privileges in order to write into the Registry, therefore you have to run the application as Administrator at least once, or setup the registry manually before using Log4JNA or whenever the location of the message file Win32EventlogAppender.dll changes in the configuration file.

The message file Win32EventlogAppender.dll

WindowsTM Event Viewer and log depends on message files to find message content, formats, categories and types.

Log4JNA uses a message file named Win32EventlogAppender.dll, we only define the categories and types and a generic message format that acts as pass through for the message format defined by your Log4j messages.

Log4JNA needs to be able to find the file in order tof

Log4JNA Configuration Parameters

Name Required Default Value Usage Description
name true N/A This required value must always be Win32EventLog.
It identifies the appender to Log4j 2TM Plugin management implementation
application false Application Indicates the top level location in the Event Viewer

The default is Windows Logs -> Application with a Source as per the source parameter.

If any other value than Application is used a Registry key in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\ is created and Log4JNA will log into Application and Service Logs -> <application-value> with a Source column as per the source parameter.
source false Log4jnaTest Indicates the text to use in the Source column in the Event Viewer.
We strongly recommend to use a different value
eventMessageFile true N/A Indicates the file system location of the message file
The value can be relative as far as the program can determinate the absolute location in the file system.
categoryMessageFile true N/A Indicates the file system location of the message file
The value can be relative as far as the program can determinate the absolute location in the file system.

Log4JNA Registry Entries

All entries are created in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\.

The final location is defined by the application and source configuration parameters.

Entry name Entry Type Value User Configurable
TypesSupported DWORD (32 bit) Value (REG_DWORD) 0x7 NO
CategoryCount DWORD (32 bit) Value (REG_DWORD) 0x6 NO
EventMessageFile String Value (REG_SZ) <Full path to>\Win32EventlogAppender.dll YES
CategoryMessageFile String Value (REG_SZ) <Full path to>\Win32EventlogAppender.dll YES

Log4J 2 configuration

Sample configuration files are provide in the Log4JNA Demo project and we use them for this examples.

All Log4j 2TM configuration formats are supported, we show here .xml and .properties configuration examples, for json, yaml, and strict xml configuration follow the Log4j 2TM documentation.

Configuring with all default values.

log4j2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="TRACE">
  <Properties>
    ...
    
    <!-- Message file location -->
    <Property name="dllfile">src\main\resources\Win32EventLogAppender.dll</Property>
    
    ...
  </Properties>

  <Appenders>
    ...
    
    <Win32EventLog name="Win32EventLog" eventMessageFile="${dllfile}" categoryMessageFile="${dllfile}">
      <PatternLayout pattern="%-5p [%t] %m%n" />
    </Win32EventLog>
    
    ...
  </Appenders>
</Configuration>

log4j2.properties

status=trace
...
appender.winlogger.type = Win32EventLog
appender.winlogger.name = Win32EventLog
appender.winlogger.eventMessageFile=src\\main\\resources\\Win32EventLogAppender.dll
appender.winlogger.categoryMessageFile=src\\main\\resources\\Win32EventLogAppender.dll
appender.winlogger.layout.type = PatternLayout
appender.winlogger.layout.pattern = %d{yyyy-MM-dd HH:mm:ss} %c{1} [%p] %m%n

logger.winlogger.level = debug
logger.winlogger.appenderRef.winlogger.ref = Win32EventLog

...

This configuration will result in the creation of Registry entries in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Log4jnaTest and writing to the Event Viewer Windows Logs\Application with a Source column value of Log4jnaTest

Configuring with default location and named Source.

log4j2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="TRACE">
  <Properties>
    ...
    
    <!-- Message file location -->
    <Property name="dllfile">src\main\resources\Win32EventLogAppender.dll</Property>
    
    ...
  </Properties>

  <Appenders>
    ...
    
    <Win32EventLog name="Win32EventLog" source="WinLogger" eventMessageFile="${dllfile}" 
        categoryMessageFile="${dllfile}">
      <PatternLayout pattern="%-5p [%t] %m%n" />
    </Win32EventLog>
    
    ...
  </Appenders>
</Configuration>

log4j2.properties

status=trace
...
appender.winlogger.type = Win32EventLog
appender.winlogger.name = Win32EventLog
appender.winlogger.source=WinLogger
appender.winlogger.eventMessageFile=src\\main\\resources\\Win32EventLogAppender.dll
appender.winlogger.categoryMessageFile=src\\main\\resources\\Win32EventLogAppender.dll
appender.winlogger.layout.type = PatternLayout
appender.winlogger.layout.pattern = %d{yyyy-MM-dd HH:mm:ss} %c{1} [%p] %m%n

logger.winlogger.level = debug
logger.winlogger.appenderRef.winlogger.ref = Win32EventLog

...

This configuration will result in the creation of Registry entries in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\WinLogger and writing to the Event Viewer Windows Logs\Application with a Source column value of WinLogger

Configuring all values.

log4j2.xml

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="TRACE">
  <Properties>
    ...
    
    <!-- Message file location -->
    <Property name="dllfile">src\main\resources\Win32EventLogAppender.dll</Property>
    
    ...
  </Properties>

  <Appenders>
    ...
    
    <Win32EventLog name="Win32EventLog" source="WinLogger" application="Win32LogApplication" 
        eventMessageFile="${dllfile}" categoryMessageFile="${dllfile}">
      <PatternLayout pattern="%-5p [%t] %m%n" />
    </Win32EventLog>
    
    ...
  </Appenders>
</Configuration>

log4j2.properties

status=trace
...
appender.winlogger.type = Win32EventLog
appender.winlogger.name = Win32EventLog
appender.winlogger.source=WinLogger
appender.winlogger.application=Win32LogApplication 
appender.winlogger.eventMessageFile=src\\main\\resources\\Win32EventLogAppender.dll
appender.winlogger.categoryMessageFile=src\\main\\resources\\Win32EventLogAppender.dll
appender.winlogger.layout.type = PatternLayout
appender.winlogger.layout.pattern = %d{yyyy-MM-dd HH:mm:ss} %c{1} [%p] %m%n

logger.winlogger.level = debug
logger.winlogger.appenderRef.winlogger.ref = Win32EventLog

...

This configuration will result in the creation of Registry entries in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Win32LogApplicationger\WinLogger and writing to the Event Viewer Applications and Service Logs\Win32LogApplication with a Source column value of WinLogger

Registry set up

All Defaults

  1. Open regedit and browse to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\
  2. Right click and select New Key, name it Log4jnaTest
  3. Add the following entries to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Log4jnaTest

The registry should look like this:

Registry Img

Espefiying the Source in the Default logger (Recommended)

  1. Open regedit and browse to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\
  2. Right click and select New Key, give it a unique name that identifies your application.
  3. Add the registry entries to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Log4jnaTest

The registry should look like this:

Registry Img

Using your own application entries in Event Viwer

Here we use the Log4J Demo values as an example.

  1. Open regedit and browse to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\
  2. Right click and select New Key, name it Win32LogApplication
  3. Add another key to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Win32LogApplication, name it WinLogger
  4. Add the registry entries to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Win32LogApplication\WinLogger

The registry should look like this:

Registry Img

Dependencies

Log4JNA depends on log4j-core, log4j-api, jna-plaform and jna.

Place the dependencies in a location visible in the CLASSPATH.

Verify that the dependencies are not already provided by an Application Sever at the server class loader level.

Place the JNA dependencies at the Application Server class loader level and declare JNA dependencies as provided in your build.

The same principle can be applied for Log4JNA and log4j dependencies in an Application Server if several applications log to the Event Viewer.

On Application Servers consider placing the message file ``

Here is an example of Tomcat dependencies distribution on the file system for a single application.

 Apche Tomcat
       |+ bin
       |+ conf
       |+ lib
       |   |+ jna-core.jar
       |   |+ jna.jar
       |+ logs
       |+ temp
       |+ webapps
       |     |+ your-application
       |               |+ WEBINF
       |                     |+ lib
       |                         |+ log4jna-api.jar
       |                         |+ lo4j-core.jar
       |                         |+ log4j-api.jar
       |                         |+ Win32EventlogAppender.dll
       |+ work

Here is an example of Tomcat dependencies distribution on the file system for multiple applications.

 Apche Tomcat
       |+ bin
       |+ conf
       |+ lib
       |   |+ jna-core.jar
       |   |+ jna.jar
       |   |+ log4jna-api.jar
       |   |+ lo4j-core.jar
       |   |+ log4j-api.jar
       |   |+ Win32EventlogAppender.dll
       |+ logs
       |+ temp
       |+ webapps
       |     |+ your-application 1
       |     |         |+ WEBINF
       |     |               |+ lib
       |     |                   |+ other-dependencies.jar
       |     |+ your-application 2
       |               |+ WEBINF
       |                     |+ lib
       |                         |+ other-dependencies.jar
       |+ work