Go (xm_go)

This module provides support for processing NXLog Agent log data with methods written in the Go language. The file specified by the ImportLib directive should contain one or more methods which can be called from the Exec directive of any module. See also the im_go and om_go modules.

For the system requirements, installation details, and environmental configuration requirements of Go, see the Getting Started section in the Go documentation. The Go environment is only needed for compiling the Go file. NXLog Agent does not need the Go environment for its operation.

The Go script imports the NXLog module and will have access to the following classes and functions.

class nxModule

This class is instantiated by NXLog Agent and can be accessed via the nxLogdata.module attribute. This can be used to set or access variables associated with the module (see the example below).

nxmodule.NxLogdataNew(*nxLogdata): This function creates a new log data record.
nxmodule.Post(ld *nxLogdata): This function puts log data struct for further processing.
nxmodule.AddEvent(): This function adds a READ event to NXLog Agent and allows you to call it later.
nxmodule.AddEventDelayed(mSec C.int): This function adds a delayed READ event to NXLog Agent and allows you to call it later.

class nxLogdata

This class represents an event. It is instantiated by NXLog Agent and passed to the method specified by the go_call() function.

nxlogdata.Get(field string) (interface{}, bool): This function returns the value/exists pair for the logdata field.
nxlogdata.GetString(field string) (string, bool): This function returns the value/exists pair for the string representation of the logdata field.
nxlogdata.Set(field string, val interface{}): This function sets the logdata field value.
nxlogdata.Delete(field string): This function removes the field from logdata.
nxlogdata.Fields() []string: This function returns an array of field names in the logdata record.

module: This attribute is set to the module object associated with the event.

Installing the gonxlog.go file

For the Go environment to work with NXLog Agent, the gonxlog.go file has to be installed.

This applies to Linux only.

Copy the gonxlog.go file from the /opt/nxlog/lib/nxlog/modules/extension/go/gopkg/nxlog.co/gonxlog/ directory to the $GOPATH/src/nxlog.co/gonxlog/ directory.
Change directory to $GOPATH/src/nxlog.co/gonxlog/.
Execute the go install gonxlog.go command to install the file.

Compiling the Go file

In order to be able to call Go functions, the Go file must be compiled into a shared object file that has the .so extension. The syntax for compiling the Go file is the following.

go build -o /path/to/yoursofile.so -buildmode=c-shared /path/to/yourgofile.go

Configuration

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

Required directives

The following directives are required for the module to start.

ImportLib

This mandatory directive specifies the file containing the Go code compiled into a shared library .so file.

Exec

This mandatory directive uses the go_call(function) which must accept an nxLogData() object as its only argument. For this directive, any number of go_call(function) may be defined as displayed below.

Exec go_call("process", "arg1", "arg2", ..., "argN")

Procedures

The following procedures are exported by xm_go.

call(string subroutine);: Call the given GoLang subroutine.

go_call(string subroutine, varargs args);: Call the given GoLang subroutine.

Configuration templates

In this Go file template, a simple function is called via the go_call("process"); argument using the Exec directive.

xm_go simple template

//export process
func process(ctx unsafe.Pointer) {
    // get logdata from the context
    if ld, ok := gonxlog.GetLogdata(ctx); ok {
        // llace your code here
    }
}

In this Go file template, a multi-argument function is called via the go_call("process", "arg1", "arg2", …, "argN") argument using the Exec directive.

xm_go multi-argument template

//export process
func process(ptr unsafe.Pointer) {
    // get logdata from the context
    if data, ok := gonxlog.GetLogdata(ptr); ok {
    // place your code here
    // get additional arguments
    for i := 0; i < gonxlog.GetArgc(ptr); i++ {
        // iterate through additional args: "arg1", "arg2", ..., "argN"
        if arg, ok := gonxlog.GetArg(ptr, i); ok {
            // place your your additional argument here
        }
    }
}

Examples

Example 1. Using xm_go for log processing

This configuration calls the go_call process in the compiled external Go language shared object file to mask the IPv4 addresses in the input file, so they are replaced with x.x.x.x in the output file.

nxlog.conf

<Extension ext>
    Module       xm_go
    ImportLib    "file/process.so"
</Extension>

<Input in1>
    Module    im_file
    File      "file/input.txt"
</Input>

<Output out>
    Module    om_file
    File      "file/output.txt"
    Exec      go_call("process");
</Output>

xm_go file sample

//export write
func process(ctx unsafe.Pointer) {
    if ld, ok := gonxlog.GetLogdata(ctx); ok {
        if rawEvent, ok := ld.GetString("raw_event"); ok {
            ld.Set("raw_event", re.ReplaceAllStringFunc(rawEvent, func(word string) \
            string {
                if wordIsIpv4Address(word) {
                    return "x.x.x.x"
                }
                return word
            }))
        }
    }
}

Input sample

Sep 30 14:20:24 mephisto vmnet-dhcpd: Configured subnet: 192.168.169.0
Sep 30 14:20:24 mephisto vmnet-dhcpd: Setting vmnet-dhcp IP address: 192.168.169.254
Sep 30 14:20:24 mephisto vmnet-dhcpd: Recving on     VNet/vmnet1/192.168.169.0
Sep 30 14:20:24 mephisto kernel: /dev/vmnet: open called by PID 3243 (vmnet-dhcpd)
Sep 30 14:20:24 mephisto vmnet-dhcpd: Sending on     VNet/vmnet1/192.168.169.0

Output sample

Sep 30 14:20:24 mephisto vmnet-dhcpd: Configured subnet: x.x.x.x
Sep 30 14:20:24 mephisto vmnet-dhcpd: Setting vmnet-dhcp IP address: x.x.x.x
Sep 30 14:20:24 mephisto vmnet-dhcpd: Recving on     VNet/vmnet1/x.x.x.x
Sep 30 14:20:24 mephisto kernel: /dev/vmnet: open called by PID 3243 (vmnet-dhcpd)
Sep 30 14:20:24 mephisto vmnet-dhcpd: Sending on     VNet/vmnet1/x.x.x.x