Java (xm_java)

This module provides support for processing NXLog Agent log data with methods written in the Java language. The Java classes specified via the ClassPath directive may define one or more class methods which can be called from the Exec directive of NXLog Agent modules via the functions provided by the xm_java 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 om_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 the 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 has the same functionality as the core log_info() procedure.
NXLog.logDebug(msg): This method sends the message msg to the internal logger at DEBUG log level. It has the same functionality as the core log_debug() procedure.
NXLog.logWarning(msg): This method sends the message msg to the internal logger at WARNING log level. It has the same functionality as the core [log_warning() procedure.
NXLog.logError(msg): This method sends the message msg to the internal logger at ERROR log level. It has the same functionality as the core log_error() procedure.

Configuration

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

The xm_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.

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 Agent 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.

Procedures

The following procedures are exported by xm_java.

call(string method, varargs args);: Call the given Java static method.

java_call(string method, varargs args);: Call the given Java static method.

Examples

Example 1. Using the xm_java module for processing logs

Below is an example of module usage. The process1 and process2 methods of the Extension Java class split log data into key-value pairs and add an additional field to each entry. The results are then converted to JSON format.

nxlog.conf

<Extension ext>
    Module          xm_java
    # Path to the compiled Java class
    Classpath       Extension.jar
</Extension>

<Output fileout>
    Module          om_file
    File            '/tmp/output'
    # Calling the first method to split data into key-value pairs
    Exec            java_call("Extension.process1");
    # Calling the second method and passing the additional parameter
    Exec            ext->call("Extension.process2", "test");
    Exec            to_json();
</Output>

Below is the Java class with comments.

Extension.java

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardOpenOption;

public class Extension {

    // The first method used by the NXLog module
    // The NXLog.Logdata ld is a mandatory parameter
    // This method should be public and static
    public static void process1(NXLog.Logdata ld) {
        // This method splits logdata into key-value pairs
        String rawEvent = (String) ld.getField("raw_event");
        String[] pairs = rawEvent.split(" ");

        for (String v : pairs) {
            if (v.isEmpty()) continue;
            String[] kv = v.split("=");
            // Adds new fields to the logdata
            ld.setField(kv[0], kv[1]);
        }
    }

    // The second method used by the NXLog module
    // The NXLog.Logdata ld is as mandatory parameter
    // This method should be public and static
    public static void process2(NXLog.Logdata ld, String stage) {
        String type = (String) ld.getField("type");
        // Deletes fields
        ld.deleteField("EventReceivedTime");
	      ld.deleteField("SourceModuleName");
        ld.deleteField("SourceModuleType");
        // Creats the additional "Stage" field with a value
        ld.setField("Stage",stage);
        if (type == null) {
            return;
        }

        if (type.equals("CWD")) {
            try {
                NXLog.logInfo(String.format("type: %s", type));
                Files.write(
                        Paths.get("tmp/processed"),
                        ((String) ld.getField("raw_event") + "\n").getBytes(),
                        StandardOpenOption.APPEND,
                        StandardOpenOption.CREATE
                );
            } 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

{
  "type":"CWD",
  "msg":"audit(1489999368.711:35724):",
  "cwd":"\"/root/nxlog\"",
  "Stage":"test"
}
{
  "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",
  "Stage":"test"
}
{
  "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)",
  "Stage":"test"
}