Core functions

The following functions are exported by core.

type: boolean array_pop(type: array array_value)

This removes the highest index element from the container array_value. It returns TRUE on succesful removal or FALSE on empty container or if the type of array_value is not an array.

type: binary base64decode(type: string base64str)

Return the decoded binary value of base64str.

type: string base64encode(type: unknown arg)

Return the BASE64 encoded string of arg, which can be either string or binary.

type: string bin2str(type: binary arg)

Return the raw string from the binary value of arg. ASCII null characters in arg will be converted to periods (.) in the returned string value. This function is intended for debugging purposes.

type: datetime datetime(type: integer arg)

Convert the integer argument, expressing the number of microseconds since epoch, to datetime.

type: integer day(type: datetime datetime)

Return the day part of the time value.

type: integer day(type: datetime datetime, type: boolean utc)

Return the day part of the time value. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: integer dayofweek(type: datetime datetime)

Return the number of days since Sunday in the range of 0-6.

type: integer dayofweek(type: datetime datetime, type: boolean utc)

Return the number of days since Sunday in the range of 0-6. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: integer dayofyear(type: datetime datetime)

Return the day number of the year in the range of 1-366.

type: integer dayofyear(type: datetime datetime, type: boolean utc)

Return the day number of the year in the range of 1-366. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: unknown deserialize(type: binary value)

It returns the de-serialized value of the value. If value is not a binary type or the format does not match the nxlog internal format then it returns an undef value.

type: boolean dropped()

Return TRUE if the currently processed event has already been dropped.

type: string escape_html(type: string html)

Return the HTML escaped html string.

type: string escape_json(type: string jsonstr)

Escape and return jsonstr according to the JSON specification.

type: string escape_url(type: string url)

Return the URL encoded string for url.

type: string escape_xml(type: string xmlstr)

Return the XML escaped xmlstr string.

type: boolean failed_over()

Returns TRUE if the current module is not connected to the first configured Host.

type: boolean failed_over(type: string modulename)

Returns TRUE if the module given by modulename is not connected to it’s first configured Host.

type: datetime fix_year(type: datetime datetime)

Return a corrected datetime value for a datetime which was parsed with a missing year, such as BSD Syslog or Cisco timestamps. The current year is used unless it would result in a timestamp that is more than 30 days in the future, in which case the previous year is used instead. If using the current year results in a timestamp that is less than or equal to 30 days in the future, it is assumed that the source device’s clock is incorrect (and the returned datetime value will be up to 30 days in the future).

type: string get_instance_id()

Return the NXLog Agent agent unique identifier (UID).

type: integer get_rand()

Return a random integer value.

type: integer get_rand(type: integer max)

Return a random integer value between 0 and max.

type: unknown get_registryvalue(type: string mainkey, type: string subkeys, type: string valuename, type: boolean 64bit_view)

Return a value from the Windows Registry. mainkey must be one of the following predefined registry keys: HKCC, HKU, HKCU, HKCR, or HKLM. subkeys must be a series of backslash-separated valid Registry keys to open from mainkey. valuename must be a valid name of a value in last key of the subkeys. If 64bit_view is FALSE, then it indicates that 64-bit Windows should operate on the 32-bit Registry view; otherwise 64-bit Windows should operate on the 64-bit Registry view. Returns the value belonging to valuename. Returns undef if valuename or any of the subkeys can not be accessed in the Registry.

type: integer get_sequence(type: string name)

Return a number for the specified sequence that is incremented after each call to this function.

type: integer get_stat(type: string statname)

Return the value of the statistical counter or undef if it does not exist.

type: integer get_stat(type: string statname, type: datetime time)

Return the value of the statistical counter or undef if it does not exist. The time argument specifies the current time.

type: string get_uuid()

Return a UUID string.

type: unknown get_var(type: string varname)

Return the value of the variable or undef if it does not exist.

type: ipaddr host_ip()

Return the first non-loopback IP address the hostname resolves to.

type: ipaddr host_ip(type: integer nth)

Return the nth non-loopback IP address the hostname resolves to. The nth argument starts from 1.

type: string hostname()

Return the hostname (short form).

type: string hostname_fqdn()

Return the FQDN hostname. This function will return the short form if the FQDN hostname cannot be determined.

type: integer hour(type: datetime datetime)

Return the hour part of the time value.

type: integer hour(type: datetime datetime, type: boolean utc)

Return the hour part of the time value. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: integer integer(type: unknown arg)

Parse and convert the string argument to an integer. For datetime type it returns the number of microseconds since epoch.

type: ipaddr ipaddr(type: integer arg)

Convert the integer argument to an ipaddr type.

type: ipaddr ipaddr(type: integer arg, type: boolean ntoa)

Convert the integer argument to an ipaddr type. If ntoa is set to true, the integer is assumed to be in network byte order. Instead of 1.2.3.4 the result will be 4.3.2.1.

type: string lc(type: string arg)

Convert the string to lower case.

type: string md5sum(type: unknown arg)

Return the MD5 hash of arg as a hexadecimal string. arg can be either string or binary.

type: unknown md5sum(type: unknown arg, type: boolean isbinary)

Return the MD5 hash of arg as a binary value or a hexadecimal string. When isbinary is TRUE, the return type will be binary. arg can be either string or binary.

type: integer microsecond(type: datetime datetime)

Return the microsecond part of the time value.

type: integer microsecond(type: datetime datetime, type: boolean utc)

Return the microsecond part of the time value. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: integer minute(type: datetime datetime)

Return the minute part of the time value.

type: integer minute(type: datetime datetime, type: boolean utc)

Return the minute part of the time value. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: integer month(type: datetime datetime)

Return the month part of the datetime value.

type: integer month(type: datetime datetime, type: boolean utc)

Return the month part of the datetime value. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: datetime now()

Return the current time.

type: string nxlog_version()

Return the NXLog Agent version string.

type: datetime parsedate(type: string arg)

Parse a string containing a timestamp. Dates without timezone information are treated as local time. The current year is used for formats that do not include the year. An undefined datetime type is returned if the argument cannot be parsed, so that the user can fix the error (for example, $EventTime = parsedate($somestring); if not defined($EventTime) $EventTime = now();). Supported timestamp formats are listed below.

RFC 3164 (legacy Syslog) and variations

Nov 6 08:49:37
Nov  6 08:49:37
Nov 06 08:49:37
Nov 3 14:50:30.403
Nov  3 14:50:30.403
Nov 03 14:50:30.403
Nov 3 2005 14:50:30
Nov  3 2005 14:50:30
Nov 03 2005 14:50:30
Nov 3 2005 14:50:30.403
Nov  3 2005 14:50:30.403
Nov 03 2005 14:50:30.403
Nov 3 14:50:30 2005
Nov  3 14:50:30 2005
Nov 03 14:50:30 2005

RFC 1123

RFC 1123 compliant dates are also supported, including a couple others which are similar such as those defined in RFC 822, RFC 850, and RFC 1036.

Sun, 06 Nov 1994 08:49:37 GMT  ; RFC 822, updated by RFC 1123
Sunday, 06-Nov-94 08:49:37 GMT ; RFC 850, obsoleted by RFC 1036
Sun Nov  6 08:49:37 1994       ; ANSI C's asctime() format
Sun, 6 Nov 1994 08:49:37 GMT   ; RFC 822, updated by RFC 1123
Sun, 06 Nov 94 08:49:37 GMT    ; RFC 822
Sun,  6 Nov 94 08:49:37 GMT    ; RFC 822
Sun, 6 Nov 94 08:49:37 GMT     ; RFC 822
Sun, 06 Nov 94 08:49 GMT       ; Unknown
Sun, 6 Nov 94 08:49 GMT        ; Unknown
Sun, 06 Nov 94 8:49:37 GMT     ; Unknown [Elm 70.85]
Sun, 6 Nov 94 8:49:37 GMT      ; Unknown [Elm 70.85]
Mon,  7 Jan 2002 07:21:22 GMT  ; Unknown [Postfix]
Sun, 06-Nov-1994 08:49:37 GMT  ; RFC 850 with four digit years

The above formats are also recognized when the leading day of week and/or the timezone are omitted.

Apache/NCSA date

This format can be found in Apache access logs and other sources.

24/Aug/2009:16:08:57 +0200

ISO 8601 and RFC 3339

NXLog Agent can parse the ISO format with or without sub-second resolution, and with or without timezone information. It accepts either a comma (,) or a dot (.) in case there is sub-second resolution.

1977-09-06 01:02:03
1977-09-06 01:02:03.004
1977-09-06T01:02:03.004Z
1977-09-06T01:02:03.004+02:00
2011-5-29 0:3:21
2011-5-29 0:3:21+02:00
2011-5-29 0:3:21.004
2011-5-29 0:3:21.004+02:00

Windows timestamps

20100426151354.537875
20100426151354.537875-000
20100426151354.537875000
3/13/2017 8:42:07 AM      ; Microsoft DNS Server

Integer timestamp

This format is XXXXXXXXXX.USEC. The value is expressed as an integer showing the number of seconds elapsed since the epoch UTC. The fractional microsecond part is optional.

1258531221.650359
1258531221

BIND9 timestamps

23-Mar-2017 06:38:30.143
23-Mar-2017 06:38:30
2017-Mar-23 06:38:30.143
2017-Mar-23 06:38:30

type: datetime parsedate(type: string arg, type: boolean utc)

Dates without timezone information are treated as UTC when utc is TRUE. If utc is FALSE, input strings are parsed in local time—the same behavior as parsedate(arg).

type: string replace(type: string subject, type: string src, type: string dst)

Replace all occurrences of src with dst in the subject string.

type: string replace(type: string subject, type: string src, type: string dst, type: integer count)

Replace count number occurrences of src with dst in the subject string.

type: integer second(type: datetime datetime)

Return the second part of the time value.

type: integer second(type: datetime datetime, type: boolean utc)

Return the second part of the time value. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.

type: binary serialize(type: unknown value)

It returns the serialized (binary) representation of the value.

type: string sha1sum(type: unknown arg)

Return the SHA1 hash of arg as a hexadecimal string. arg can be either string or binary.

type: unknown sha1sum(type: unknown arg, type: boolean isbinary)

Return the SHA1 hash of arg as a binary value or a hexadecimal string. When isbinary is TRUE, the return type will be binary. arg can be either string or binary.

type: string sha512sum(type: unknown arg)

Return the SHA512 hash of arg as a hexadecimal string. arg can be either string or binary.

type: unknown sha512sum(type: unknown arg, type: boolean isbinary)

Return the SHA512 hash of arg as a binary value or a hexadecimal string. When isbinary is TRUE, the return type will be binary. arg can be either string or binary.

type: unknown size(type: unknown value)

If value is a string or binary type, it returns the size of value in bytes. If value is a map or array type, it returns the number of elements in value. Otherwise, if value is another type or undef, the function returns undef.

type: boolean str_compare(type: string haystack, type: string needle, type: boolean case_sensitive)

This returns TRUE if the haystack has the same value as the needle , and FALSE otherwise. If case_sensitive is TRUE, then the comparison will be case-sensitive, otherwise not.

type: boolean str_contains(type: string haystack, type: string needle, type: boolean case_sensitive)

This returns TRUE if the haystack contains the needle , and FALSE otherwise. If case_sensitive is TRUE, then the comparison will be case-sensitive, otherwise not.

type: boolean str_ends_with(type: string haystack, type: string needle, type: boolean case_sensitive)

This returns TRUE if the haystack ends with the needle , and FALSE otherwise. If case_sensitive is TRUE, then the comparison will be case-sensitive, otherwise not.

type: boolean str_starts_with(type: string haystack, type: string needle, type: boolean case_sensitive)

This returns TRUE if the haystack begins with the needle , and FALSE otherwise. If case_sensitive is TRUE, then the comparison will be case-sensitive, otherwise not.

type: string strftime(type: datetime datetime, type: string fmt)

Convert a datetime value to a string with the given format. The format must be one of:

YYYY-MM-DD hh:mm:ss,
YYYY-MM-DDThh:mm:ssTZ,
YYYY-MM-DDThh:mm:ss.sTZ,
YYYY-MM-DD hh:mm:ssTZ,
YYYY-MM-DD hh:mm:ss.sTZ,
YYYY-MM-DDThh:mm:ssUTC,
YYYY-MM-DDThh:mm:ss.sUTC,
YYYY-MM-DD hh:mm:ssUTC,
YYYY-MM-DD hh:mm:ss.sUTC, or
a format string accepted by the C strftime() function (see the strftime(3) manual or the Windows strftime reference for the format specification).

type: string string(type: unknown arg)

Convert the argument to a string.

type: datetime strptime(type: string input, type: string fmt)

Convert the string to a datetime with the given format. See the manual of strptime(3) for the format specification.

type: string substr(type: string src, type: integer from)

Return the string starting at the byte offset specified in from.

type: string substr(type: string src, type: integer from, type: integer to)

Return a sub-string specified with the starting and ending positions as byte offsets from the beginning of the string.

type: string type(type: unknown arg)

Returns the variable type: array, binary, boolean, datetime, hash, integer, ipaddr, regexp, or string. When the value is undef or the variable does not exist, type() returns a visually empty value that equals to undef. This value is neither an empty string ("") nor the string "undef". While the undef type cannot be directly output as a value, it can be checked programmatically.

type: string uc(type: string arg)

Convert the string to upper case.

type: string unescape_html(type: string html)

Return the HTML unescaped html string.

type: string unescape_json(type: string jsonstr)

Unescape and return jsonstr according to the JSON specification.

type: string unescape_url(type: string url)

Return the URL decoded string for url.

type: string unescape_xml(type: string xmlstr)

Return the XML unescaped xmlstr string.

type: integer year(type: datetime datetime)

Return the year part of the datetime value.

type: integer year(type: datetime datetime, type: boolean utc)

Return the year part of the datetime value. Optionally in UTC time if utc is set to TRUE, localtime if FALSE. If not set, honors the GenerateDateInUTC directive.