Python (om_python)

This module enables you to process and forward logs using a custom Python script. Only Python version 3 and its minor releases are currently supported. See the Python prerequisites for using this module on Windows.

The script specified by the PythonCode directive should contain a write_data() function, which the om_python module instance will call. In addition, see also the xm_python and im_python modules.

To examine the supported platforms, see the list of installer packages in the Available Modules chapter.

The Python script must import the nxlog module to access the following classes and methods.

nxlog.log_debug(msg): Send the message msg to the internal logger at DEBUG log level. This function does the same as the core log_debug() procedure.
nxlog.log_info(msg): Send the message msg to the internal logger at INFO log level. This function does the same as the core log_info()procedure.
nxlog.log_warning(msg): Send the message msg to the internal logger at WARNING log level. This function does the same as the core log_warning() procedure.
nxlog.log_error(msg): Send the message msg to the internal logger at ERROR log level. This function does the same as the core log_error() procedure.
class nxlog.Module: This class is instantiated by NXLog and can be accessed via the LogData.module attribute. This can be used to set or access variables associated with the module (see the example below).

class nxlog.LogData

This class represents an event. It is instantiated by NXLog and passed to the write_data() method.

delete_field(name): This method removes the field name from the event record.
field_names(): This method returns a list with the names of all the fields currently in the event record.
get_field(name): This method returns the value of the field name in the event.
set_field(name, value): This method sets the value of field name to value.

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

Python prerequisites for Windows

om_python is available on Windows as of NXLog version 5.5 and newer. Before using this module, you must ensure that the correct Python version is installed and that NXLog can load it.

Install Python manually

These steps install Python for all users on the machine, which is required when the NXLog service is running under the default Local System account. If you are using a custom service user, you may install Python for only that user.

Download the required Python version according to your NXLog installation. See the NXLog and Python version matrix below.
Execute the installation wizard and in the first step, choose Customize installation.
Select any optional features and click Next.
Select Install Python 3.0 for all users and Add Python to environment variables advanced options.
Take note of the install location and click Install.
When the installation is complete, open the Python installation folder.
Copy the Python DLL, e.g., python310.dll, to the NXLog installation folder.
Rename the file to libpython<major_version>.<minor_version>.dll. See the table below.
Restart the NXLog service.

Automated Python installation

The following PowerShell script downloads Python, installs it, and copies the necessary DLL file to the NXLog installation folder. You must specify the required Python version according to your NXLog installation in the $ver variable. See the NXLog and Python version matrix below.

install_python.ps1

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

$ver="3.10.8"

$baseuri="https://www.python.org/ftp/python/" + $ver
$msifile="python-" + $ver +"-amd64.exe"
Invoke-WebRequest -uri $baseuri/$msifile -OutFile $msifile

$sdotver=$ver -replace '([0-9]*)\.([0-9]*)\.([0-9]*)', '$1.$2'
$sver=$sdotver -replace '\.',''

$pydll='C:\Program Files\Python' + $sver + '\python' + $sver + '.dll'
$nxpydll='C:\Program Files\nxlog\libpython' + $sdotver + '.dll'

& ./$msifile /quiet InstallAllUsers=1 PrependPath=1 CompileAll=1

DO
{
   Start-Sleep -s 2
   Write-Host -NoNewline .
}
until (Test-Path $pydll )

Write-Host
Write-Host "Copying DLL: $pydll -> $nxpydll"

cp $pydll $nxpydll

This script is provided "AS IS" without warranty of any kind, either expressed or implied. Use at your own risk.

NXLog and Python version matrix

NXLog version	Python version	DLL filename
5.5.x	3.9.x	libpython3.9.dll
5.6.x	3.10.x	libpython3.10.dll

NXLog version

Python version

DLL filename

5.5.x

3.9.x

libpython3.9.dll

5.6.x

3.10.x

libpython3.10.dll

Configuration

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

PythonCode: This mandatory directive specifies a file containing Python code. The om_python instance will call a write_data() function which must accept an nxlog.LogData object as its only argument.

Call: This optional directive specifies the Python method to invoke. With this directive, you can call only specific methods from your Python code. If the directive is not specified, the default method write_data is invoked.

Examples

Example 1. Forwarding Events With om_python

This example shows an alerter implemented as an output module instance in Python. First, any event with a normalized severity less than of 4/ERROR is dropped; see the Exec directive (xm_syslog and most other modules set a normalized $SeverityValue field). Then the Python function generates a custom email and sends it via SMTP.

nxlog.conf

<Output out>
    Module      om_python
    PythonCode  /opt/nxlog/etc/output.py
    Exec        if $SeverityValue < 4 drop();
</Output>

output.py

from email.mime.text import MIMEText
import pprint
import smtplib
import socket

import nxlog

HOSTNAME = socket.gethostname()
FROM_ADDR = 'nxlog@{}'.format(HOSTNAME)
TO_ADDR = 'you@example.com'

def write_data(event):
    nxlog.log_debug('Python alerter received event')

    # Convert field list to dictionary
    all = {}
    for field in event.get_names():
        all.update({field: event.get_field(field)})

    # Create message from event
    pretty_event = pprint.pformat(all)
    msg = 'NXLog on {} received the following alert:\n\n{}'.format(HOSTNAME,
            pretty_event)
    email_msg = MIMEText(msg)
    email_msg['Subject'] = 'Alert from NXLog on {}'.format(HOSTNAME)
    email_msg['From'] = FROM_ADDR
    email_msg['To'] = TO_ADDR

    # Send email message
    nxlog.log_debug('Sending email alert for event')
    s = smtplib.SMTP('localhost')
    s.sendmail(FROM_ADDR, [TO_ADDR], email_msg.as_string())
    s.quit()