Go (im_go)

This module provides support for collecting log data with methods written in the Go language. The file specified by the ImportLib directive should contain one or more methods that can be called from the Exec directive of any module. See also the xm_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 Agent 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. This allows you to call the READ event later.
nxmodule.AddEventDelayed(mSec C.int): This function adds a delayed READ event to NXLog Agent. This allows you to call the delayed READ event later.

class nxLogdata

This class represents an event. It is instantiated by NXLog Agent and passed to the function specified by the ImportFunc directive.

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 fields 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

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

ImportFunc

This mandatory directive calls the specified function, which must accept an unsafe.Pointer object as its only argument. This function is called when the module tries to read data. It is a mandatory function.

ImportLib

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

Configuration Template

In this Go file template, the read function is called via the ImportFunc directive.

im_go Template

//export read
func read(ctx unsafe.Pointer) { 
    // get reference to caller module
    if module, ok := gonxlog.GetModule(ctx); ok {
    // generate new logdata for NXLog
	ld := module.NxLogdataNew()
	// set 'raw_event' value
	ld.Set("raw_event", "some string data")
	// send logdata to NXLog input module
	module.Post(ld)
    }
}

Examples

Example 1. Using im_go to generate event data

This configuration reads log files from the /var/log/syslog file directory from a remote server via SSH. The code defined in the shared object library then gets the reference from the context pointer and gets data from the channel. After that, it generates new log data by setting the raw_event value and sending it to the input module by calling the read function. Finally, it is saved to a file.

nxlog.conf

<Input in1>
    Module        im_go
    ImportLib     "input/input.so"
    ImportFunc    read
</Input>

<Output out>
    Module    om_file
    File      "output/file"
    Exec      log_info($raw_event);
</Output>

im_go file sample

//export read
func read(ctx unsafe.Pointer) {
    var str string
    gonxlog.LogDebug("Read called")
    if module, ok := gonxlog.GetModule(ctx); ok {
        if strings == nil {
            gonxlog.LogError("Channel is not initialized!")
        } else {
            select {
            case str, _ = <-strings:
                ld := module.NxLogdataNew()
                ld.Set("raw_event", str)
                module.Post(ld)
                gonxlog.LogInfo("has data")
                module.AddEvent()
            default:
                gonxlog.LogInfo("no data")
                module.AddEventDelayed(50)
            }
        }
    }
}