Go (om_go)

This module provides support for forwarding 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 xm_go and im_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

This applies for Linux only.

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

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

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.

Configuration Template

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

om_go Template

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

Examples

Example 1. Using om_go for Forwarding Events

This configuration connects to and sends log data to a MongoDB database.

nxlog.conf

<Input in>
    Module      im_testgen
    MaxCount    10
</Input>

<Output out>
    Module        om_go
    ImportLib     "file/output.so"
    ImportFunc    write
</Output>

om_go file Sample

//export write
func write(ctx unsafe.Pointer) {
    if collection == nil {
        gonxlog.LogDebug("not connected, skip record")
        return
    }
    if logdata, ok := gonxlog.GetLogdata(ctx); ok {
        if rawEvent, ok := logdata.GetString("raw_event"); ok {
            insertResult, err := collection.InsertOne(context.TODO(), bson.M{
                "source":     "nxlog",
                "created_at": time.Now(),
                "raw_event":  rawEvent,
            })
            if err != nil {
                gonxlog.LogError(fmt.Sprintf("Insert error: %v", err.Error()))
            } else {
                gonxlog.LogDebug(fmt.Sprintf("Insert '%v'", insertResult))
            }
        }
    }
}