Java (om_java)

TThis module provides support for processing NXLog Agent logs with methods written in the Java language. The Java classes specified via the ClassPath directives may define one or more class methods which can be called from the Run or Exec directives of this module. Such methods must be declared with the public and static modifiers in the Java code to be accessible from NXLog Agent, and the first parameter must be of NXLog.Logdata type. See also the im_java and xm_java modules.

For the system requirements, installation details and environmental configuration requirements of Java, see the Installing Java section in the Java documentation.

The NXLog Java class provides access to the NXLog Agent functionality in the Java code. This class contains nested classes Logdata and Module with log processing methods, as well as methods for sending messages to the internal logger.

class NXLog.Logdata

This Java class provides the methods to interact with an NXLog Agent event record object:

getField(name): This method returns the value of the field name in the event.
setField(name, value): This method sets the value of field name to value.
deleteField(name): This method removes the field name from the event record.
getFieldnames(): This method returns an array with the names of all the fields currently in the event record.
getFieldtype(name): This method retrieves the field type using the value from the name field.

class NXLog.Module

The methods below allow setting and accessing variables associated with the module instance.

saveCtx(key,value): This method saves user data in the module data storage using values from the key and value fields.
loadCtx(key): This method retrieves data from the module data storage using the value from the key field.

Below is the list of methods for sending messages to the internal logger.

NXLog.logInfo(msg): This method sends the message msg to the internal logger at INFO log level. It does the same as the core log_info() procedure.
NXLog.logDebug(msg): This method sends the message msg to the internal logger at DEBUG log level. It does the same as the core log_debug() procedure.
NXLog.logWarning(msg): This method sends the message msg to the internal logger at WARNING log level. It does the same as the core log_warning() procedure.
NXLog.logError(msg): This method sends the message msg to the internal logger at ERROR log level. It does the same as the core log_error() procedure.

Configuration

The NXLog Agent process maintains only one JVM instance for all om_java, im_java or xm_java running instances. This means all classes loaded by the ClassPath directive will be available for all running Java instances.

The om_java module accepts the following directives in addition to the common module directives.

Required directives

The following directives are required for the module to start.

ClassPath

This mandatory directive defines the path to the .class files or a .jar file. This directive should be defined at least once within a module block.

Run

This mandatory directive specifies the static method inside the Classpath file which should be called.

Optional directives

JavaHome

This optional directive defines the path to the Java Runtime Environment (JRE). The path is used to search for the libjvm shared library. If this directive is not defined, the Java home directory will be set to the build-time value. Only one JRE can be defined for one or multiple NXLog Java instances. Defining multiple JRE instances causes an error.

VMOption

This optional directive defines a single Java Virtual Machine (JVM) option.

VMOptions

This optional block directive serves the same purpose as the VMOption directive, but also allows specifying multiple Java Virtual Machine (JVM) instances, one per line.

Example of Usage

Example 1. Using the om_java Module for Processing Logs

This is an example of a configuration for adding a timestamp field and writing log processing results to a file. The run method of the Writer Java class is being used to handle the processing.

Below is the NXLog Agent configuration.

nxlog.conf

<Output javaout>
    Module          om_java
    # The Run directive includes the full method name with
    # the nested and outer classes
    # The mandatory parameter will be passed automatically
    Run             Output$Writer.run
    ClassPath       Output.jar
</Output>

Below is the Java class with comments.

Output.java

import java.io.BufferedReader;
import java.io.File;
import java.io.FileReader;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardOpenOption;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.*;

public class Output {
    // The Output class utilizes a nested static class
    public static class Writer {
        static String fileName = "/tmp/output.txt";

        static Date currentDate = new Date();

        static SimpleDateFormat df = new SimpleDateFormat("MM.dd.YYYY.hh:mm:ss");

        // This is the method for the output module
        // The NXLog.Logdata ld parameter is mandatory
        static public void run(NXLog.Logdata ld) {

            try {
                // 1. Retrieves the $raw_event field from the NXLog data record
                // 2. Adds the timestamp field with the current time
                // 3. Writes the results into the file
                if (((String)ld.getField("raw_event")).contains("type=")) {
                    Files.write(Paths.get(fileName), ("timestamp=" + df.format(currentDate) + " " + (String) ld.getField("raw_event") + "\n").getBytes(), StandardOpenOption.CREATE, StandardOpenOption.APPEND);
                }
            } catch (IOException e) {
                e.printStackTrace();
            }
        }
    }
}

Below are the log samples before and after processing.

Input sample

type=CWD msg=audit(1489999368.711:35724):  cwd="/root/nxlog"

type=PATH msg=audit(1489999368.711:35724): item=0 name="/root/test" inode=528869 dev=08:01 mode=040755 ouid=0 ogid=0 rdev=00:00

type=SYSCALL msg=audit(1489999368.711:35725): arch=c000003e syscall=2 success=yes exit=3 a0=12dcc40 a1=90800 a2=0 a3=0 items=1 ppid=15391 pid=12309 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts4 ses=583 comm="ls" exe="/bin/ls" key=(null)

Output Sample

timestamp=02.20.2020.09:19:58 type=CWD msg=audit(1489999368.711:35724):  cwd="/root/nxlog"
timestamp=02.20.2020.09:19:58 type=PATH msg=audit(1489999368.711:35724): item=0 name="/root/test" inode=528869 dev=08:01 mode=040755 ouid=0 ogid=0 rdev=00:00
timestamp=02.20.2020.09:19:58 type=SYSCALL msg=audit(1489999368.711:35725): arch=c000003e syscall=2 success=yes exit=3 a0=12dcc40 a1=90800 a2=0 a3=0 items=1 ppid=15391 pid=12309 auid=0 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=pts4 ses=583 comm="ls" exe="/bin/ls" key=(null)