Return to
Portfolio

107. Language

107.1. Types

The following types are provided by the NXLog language.

Unknown

This is a special type for values where the type cannot be determined at compile time and for uninitialized values. The undef literal and fields without a value also have an unknown type. The unknown type can also be thought of as "any" in case of function and procedure API declarations.

Boolean

A boolean value is TRUE, FALSE or undefined. Note that an undefined value is not the same as a FALSE value.

Integer

An integer can hold a signed 64 bit value in addition to the undefined value. Floating point values are not supported.

String

A string is an array of characters in any character set. The binary type should be used for values where the NUL byte can also occur. An undefined string is not the same as an empty string. Strings have a limited length to prevent resource exhaustion problems, this is a compile-time value currently set to 1M.

Datetime

A datetime holds a microsecond value of time elapsed since the Epoch. It is always stored in UTC/GMT.

IPv4 Address

An ip4addr type stores a dotted-quad IPv4 address in an internal format (integer).

IPv6 Address

An ip6addr type stores an IPv6 address in an internal format.

Regular expression

A regular expression type can only be used with the =~ or !~ operators.

Binary

This type can hold an array of bytes.

Variadic arguments

This is a special type only used in function and procedure API declarations to indicate variadic arguments.

107.2. Expressions

107.2.1. Literals

Undef

The undef literal has an unknown type. It can be also used in an assignment to unset the value of a field.

Example 444. Un-Setting the Value of a Field

This statement unsets the $ProcessID field.


  
1


  
$ProcessID = undef;
Boolean

A boolean literal is either TRUE or FALSE. It is case-insensitive, so True, False, true, and false are also valid.

Integer

An integer starts with a minus (-) sign if it is negative. A "0X" or "0x" prepended modifier indicates a hexadecimal notation. The "K", "M" and "G" modifiers are also supported; these mean Kilo (1024), Mega (1024^2), or Giga (1024^3) respectively when appended.

Example 445. Setting an Integer Value

This statement uses a modifier to set the $Limit field to 44040192 (42×1024^2).


  
1


  
$Limit = 42M;
String

String literals are quoted characters using either single or double quotes. String literals specified with double quotes can contain the following escape sequences.

\\

The backslash (\) character.

\"

The double quote (") character.

\n

Line feed (LF).

\r

Carriage return (CR).

\t

Horizontal tab.

\b

Audible bell.

\xXX

A single byte in the form of a two digit hexadecimal number. For example the line-feed character can also be expressed as \x0A.

Note
 String literals in single quotes do not process the escape sequences: "\n" is a single character (LF) while '\n' is two characters. The following comparison is FALSE for this reason: "\n" == '\n'.
Note
 Extra care should be taken with the backslash when using double quoted string literals to specify file paths on Windows. For more information about the possible complications, see this note for the im_file File directive.
Example 446. Setting a String Value

This statement sets the $Message field to the specified string.


  
1


  
$Message = "Test message";
Datetime

A datetime literal is an unquoted representation of a time value expressing local time in the format of YYYY-MM-DD hh:mm:ss.

Example 447. Setting a Datetime Value

This statement sets the $EventTime field to the specified datetime value.


  
1


  
$EventTime = 2000-01-02 03:04:05;
IPv4 Address

An IPv4 literal value is expressed in dotted quad notation such as 192.168.1.1.

IPv6 Address

An IPv6 literal value is expressed by 8 groups of 16-bit hexadecimal values separated by colons (:) such as 2001:0db8:85a3:0000:0000:8a2e:0370:7334.

107.2.2. Regular Expressions

The PCRE engine is used to execute regular expressions in NXLog. For more information about the PCRE syntax, see the pcre2syntax(3) and pcre2pattern(3) man pages.

Regular expressions must be used with one of the =~ and !~ operators, and must be quoted with slashes (/) as in Perl. Captured sub-strings are accessible through numeric reference, and the full subject string is placed into $0.

Example 448. A Regular Expression Match Operation

If the regular expression matches the $Message field, the log_info() procedure is executed. The captured sub-string is used in the logged string ($1).


  
1


  
if $Message =~ /^Test (\S+)/ log_info("captured: " + $1);

It is also possible to use named capturing such that the resulting field name is defined in the regular expression.

Example 449. Regular Expression Match Using Named Capturing

This statement causes the same behavior as the previous example, but it uses named capturing instead.


  
1


  
if $Message =~ /^Test: (?<test>\S+)/ log_info("captured: " + $test);

Substitution is supported with the s/// operator. Variables and captured sub-string references cannot be used inside the regular expression or the substitution operator (they will be treated literally).

107.2.2.1. Regular Expression Modifiers

The following regular expression modifiers are supported:

g

The /g modifier can be used for global replacement.

Example 450. Replace Whitespace Occurrences

If any whitespace is found in the $SourceName field, it is replaced with underscores (_) and a log message is generated.


  
1


  
if $SourceName =~ s/\s/_/g log_info("removed all whitespace in SourceName");
s

The dot (.) normally matches any character except newline. The /s modifier causes the dot to match all characters including line terminator characters (LF and CRLF).

Example 451. Dot Matches All Characters

The regular expression in this statement will match a message that begins and ends with the given keywords, even if the message spans multiple lines.


  
1


  
if $Message =~ /^Backtrace.*END$/s drop();
m

The /m modifier can be used to treat the string as multiple lines (^ and $ match newlines within data).

i

The /i modifier does case insensitive matching.

107.2.3. Fields

Fields are referenced in the NXLog language by prepending a dollar sign ($) to the field name.

Normally, a field name may contain letters, digits, the period (.), and the underscore (_). Additionally, field names must begin with a letter or an underscore. The corresponding regular expression is:

[a-zA-Z_][a-zA-Z0-9._]*

However, those restrictions are relaxed if the field name is specified with curly braces ({}). In this case, the field name may also contain hyphens (-), parentheses (()), and spaces. The field name may also begin with any one of the allowed characters. The regular expression in this case is:

[a-zA-Z0-9._() -]+
Example 452. Referencing a Field

This statement generates an internal log message indicating the time when the message was received by NXLog.


  
1


  
log_debug('Message received at ' + $EventReceivedTime);

This statement uses curly braces ({}) to refer to a field with a hyphenated name.


  
1


  
log_info('The file size is ' + ${file-size});

A field which does not exist has an unknown type.

107.2.4. Operations

107.2.4.1. Unary Operations

The following unary operations are available. It is possible to use brackets around the operand to make it look like a function call as in the "defined" example below.

not

The not operator expects a boolean value. It will evaluate to undef if the value is undefined. If it receives an unknown value which evaluates to a non-boolean, it will result in a run-time execution error.

Example 453. Using the "not" Operand

If the $Success field has a value of false, an error is logged.


  
1


  
if not $Success log_error("Job failed");
defined

The defined operator will evaluate to TRUE if the operand is defined, otherwise FALSE.

Example 454. Using the Unary "defined" Operation

This statement is a no-op, it does nothing.


  
1


  
if defined undef log_info("never printed");

If the $EventTime field has not been set (due perhaps to failed parsing), it will be set to the current time.


  
1


  
if not defined($EventTime) $EventTime = now();
107.2.4.2. Binary Operations

The following binary operations are available.

The operations are described with the following syntax:

LEFT_OPERAND_TYPE OPERATION RIGHT_OPERAND_TYPE = EVALUATED_VALUE_TYPE

=~

This is the regular expression match operation as in Perl. This operation takes a string and a regular expression operand and evaluates to a boolean value which will be TRUE if the regular expression matches the subject string. Captured sub-strings are accessible through numeric reference (such as $1) and the full subject string is placed into $0. Regular expression based string substitution is supported with the s/// operator. For more details, see Regular Expressions.

Example 455. Regular Expression Based String Matching

A log message will be generated if the $Message field matches the regular expression.


  
1


  
if $Message =~ /^Test message/ log_info("matched");
!~

This is the opposite of =~: the expression will evaluate to TRUE if the regular expression does not match on the subject string. It can be also written as not LEFT_OPERAND =~ RIGHT_OPERAND. The s/// substitution operator is supported.

Example 456. Regular Expression Based Negative String Matching

A log message will be generated if the $Message field does not match the regular expression.


  
1


  
if $Message !~ /^Test message/ log_info("didn't match");
==

This operator compares two values for equality. Comparing a defined value with an undefined results in undef.

Example 457. Equality

A log message will be generated if $SeverityValue is 1.


  
1


  
if $SeverityValue == 1 log_info("severity is one");
!=

This operator compares two values for inequality. Comparing a defined value with an undefined results in undef.

Example 458. Inequality

A log message will be generated if $SeverityValue is not 1.


  
1


  
if $SeverityValue != 1 log_info("severity is not one");
<

This operation will evaluate to TRUE if the left operand is less than the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

Example 459. Less

A log message will be generated if $SeverityValue is less than 1.


  
1


  
if $SeverityValue < 1 log_info("severity is less than one");
<=

This operation will evaluate to TRUE if the left operand is less than or equal to the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

Example 460. Less or Equal

A log message will be generated if $SeverityValue is less than or equal to 1.


  
1


  
if $SeverityValue < 1 log_info("severity is less than or equal to one");
>

This operation will evaluate to TRUE if the left operand is greater than the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

Example 461. Greater

A log message will be generated if $SeverityValue is greater than 1.


  
1


  
if $SeverityValue > 1 log_info("severity is greater than one");
>=

This operation will evaluate to TRUE if the left operand is greater than or equal to the right operand, and FALSE otherwise. Comparing a defined value with an undefined results in undef.

Example 462. Greater or Equal

A log message will be generated if $SeverityValue is greater than or equal to 1.


  
1


  
if $SeverityValue >= 1 log_info("severity is greater than or equal to one");
and

This operation evaluates to TRUE if and only if both operands are TRUE. The operation will evaluate to undef if either operand is undefined.

boolean and boolean = boolean

Example 463. And Operation

A log message will be generated only if both $SeverityValue equals 1 and $FacilityValue equals 2.


  
1


  
if $SeverityValue == 1 and $FacilityValue == 2 log_info("1 and 2");
or

This operation evaluates to TRUE if either operand is TRUE. The operation will evaluate to undef if both operands are undefined.

boolean or boolean = boolean

Example 464. Or Operation

A log message will be generated if $SeverityValue is equal to either 1 or 2.


  
1


  
if $SeverityValue == 1 or $SeverityValue == 2 log_info("1 or 2");
+

This operation will result in an integer if both operands are integers. If either operand is a string, the result will be a string where non-string typed values are converted to strings. In this case it acts as a concatenation operator, like the dot (.) operator in Perl. Adding an undefined value to a non-string will result in undef.

Example 465. Concatenation

This statement will always cause a log message to be generated.


  
1


  
if 1 + "a" == "1a" log_info("this will be printed");
-

Subtraction. The result will be undef if either operand is undefined.

Example 466. Subtraction

This statement will always cause a log message to be generated.


  
1


  
if 4 - 1 == 3 log_info("four minus one is three");
*

Multiply an integer with another. The result will be undef if either operand is undefined.

integer * integer = integer

Example 467. Multiplication

This statement will always cause a log message to be generated.


  
1


  
if 4 * 2 == 8 log_info("four times two is eight");
/

Divide an integer with another. The result will be undef if either operand is undefined. Since the result is an integer, a fractional part is lost.

integer / integer = integer

Example 468. Division

This statement will always cause a log message to be generated.


  
1


  
if 9 / 4 == 2 log_info("9 divided by 4 is 2");
%

The modulo operation divides an integer with another and returns the remainder. The result will be undef if either operand is undefined.

integer % integer = integer

Example 469. Modulo

This statement will always cause a log message to be generated.


  
1


  
if 3 % 2 == 1 log_info("three mod two is one");
IN

This operation will evaluate to TRUE if the left operand is equal to any of the expressions in the list on the right, and FALSE otherwise. Comparing a undefined value results in undef.

unknown IN unknown, unknown …​ = boolean

Example 470. IN

A log message will be generated if $EventID is equal to any one of the values in the list.


  
1


  
if $EventID IN (1000, 1001, 1004, 4001) log_info("EventID found");
NOT IN

This operation is equivalent to NOT expr IN expr_list.

unknown NOT IN unknown, unknown …​ = boolean

Example 471. NOT IN

A log message will be generated if $EventID is not equal to any of the values in the list.


  
1


  
if $EventID NOT IN (1000, 1001, 1004, 4001) log_info("EventID not in list");
107.2.4.3. Ternary Operation

The ternary operator expr1 ? expr2 : expr3 evaluates to expr2 if expr1 is TRUE, otherwise to expr3. The parentheses as shown here are optional.

Example 472. Using the Ternary Operator

The $Important field is set to TRUE if $SeverityValue is greater than 2, or FALSE otherwise.


  
1


  
$Important = ( $SeverityValue > 2 ? TRUE : FALSE );

107.2.5. Functions

See Functions for a list of functions provided by the NXLog core. Additional functions are available through modules.

Example 473. A Function Call

This statement uses the now() function to set the field to the current time.


  
1


  
$EventTime = now();

It is also possible to call a function of a specific module instance.

Example 474. Calling a Function of a Specific Module Instance

This statement calls the file_name() and file_size() functions of a defined om_file instance named out in order to log the name and size of its currently open output file.


  
1


  
log_info('Size of output file ' + out->file_name() + ' is ' + out->file_size());

107.3. Statements

The following elements can be used in statements. There is no loop operation (for or while) in the NXLog language.

107.3.1. Assignment

The assignment operation is declared with an equal sign (=). It loads the value from the expression evaluated on the right into a field on the left.

Example 475. Field Assignment

This statement sets the $EventReceivedTime field to the value returned by the now() function.


  
1


  
$EventReceivedTime = now();

107.3.2. Block

A block consists of one or more statements within curly braces ({}). This is typically used with conditional statements as in the example below.

Example 476. Conditional Statement Block

If the expression matches, both log messages will be generated.


  
1
2
3
4
5


  
if now() > 2000-01-01 00:00:00
{
   log_info("we are in the");
   log_info("21st century");
}

107.3.3. Procedures

See Procedures for a list of procedures provided by the NXLog core. Additional procedures are available through modules.

Example 477. A Procedure Call

The log_info() procedure generates an internal log message.


  
1


  
log_info("No log source activity detected.");

It is also possible to call a procedure of a specific module instance.

Example 478. Calling a Procedure of a Specific Module Instance

This statement calls the parse_csv() procedure of a defined xm_csv module instance named csv_parser.


  
1


  
csv_parser->parse_csv();

107.3.4. If-Else

A conditional statement starts with the if keyword followed by a boolean expression and a statement. The else keyword, followed by another statement, is optional. Brackets around the expression are also optional.

Example 479. Conditional Statements

A log message will be generated if the expression matches.


  
1


  
if now() > 2000-01-01 00:00:00 log_info("we are in the 21st century");

This statement is the same as the previous, but uses brackets.


  
1


  
if ( now() > 2000-01-01 00:00:00 ) log_info("we are in the 21st century");

This is a conditional statement block.


  
1
2
3
4


  
if now() > 2000-01-01 00:00:00
{
   log_info("we are in the 21st century");
}

This conditional statement block includes an else branch.


  
1
2
3
4
5


  
if now() > 2000-01-01 00:00:00
{
   log_info("we are in the 21st century");
}
else log_info("we are not yet in the 21st century");

Like Perl, the NXLog language does not have a switch statement. Instead, this can be accomplished by using conditional if-else statements.

Example 480. Emulating "switch" With "if-else"

The generated log message various based on the value of the $value field.


  
1
2
3
4
5
6
7
8


  
if ( $value == 1 )
   log_info("1");
else if ( $value == 2 )
   log_info("2");
else if ( $value == 3 )
   log_info("3");
else
   log_info("default");
Note
 The Perl elsif and unless keywords are not supported.

107.4. Variables

A module variable can only be accessed from the same module instance where it was created. A variable is referenced by a string value and can store a value of any type.

See the create_var(), delete_var(), set_var(), and get_var() procedures.

107.5. Statistical Counters

The following types are available for statistical counters:

COUNT

Added values are aggregated, and the value of the counter is increased if only positive integers are added until the counter is destroyed or indefinitely if the counter has no expiry.

COUNTMIN

This calculates the minimum value of the counter.

COUNTMAX

This calculates the maximum value of the counter.

AVG

This algorithm calculates the average over the specified interval.

AVGMIN

This algorithm calculates the average over the specified interval, and the value of the counter is always the lowest which was ever calculated during the lifetime of the counter.

AVGMAX

Like AVGMIN, but this returns the highest value calculated during the lifetime of the counter.

RATE

This calculates the value over the specified interval. It can be used to calculate events per second (EPS) values.

RATEMIN

This calculates the value over the specified interval, and returns the lowest rate calculated during the lifetime of the counter.

RATEMAX

Like RATEMIN, but this returns the highest rate calculated during the lifetime of the counter.

GRAD

This calculates the change of the rate of the counter over the specified interval, which is the gradient.

GRADMIN

This calculates the gradient and returns the lowest gradient calculated during the lifetime of the counter.

GRADMAX

Like GRADMIN, but this returns the highest gradient calculated during the lifetime of the counter.

107.6. Functions

The following functions are exported by core.

datetime datetime(integer arg)

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

integer day(datetime datetime)

Return the day part of the time value.

integer dayofweek(datetime datetime)

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

integer dayofyear(datetime datetime)

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

boolean dropped()

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

string escape_html(string html)

Return the HTML escaped html string.

string escape_json(string jsonstr)

Escape and return jsonstr according to the JSON specification.

string escape_url(string url)

Return the URL encoded string for url.

string escape_xml(string xmlstr)

Return the XML escaped xmlstr string.

datetime fix_year(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).

integer get_rand()

Return a random integer value.

integer get_rand(integer max)

Return a random integer value between 0 and max.

unknown get_registryvalue(string mainkey, string subkeys, string valuename, 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.

integer get_sequence(string name)

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

integer get_stat(string statname)

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

integer get_stat(string statname, datetime time)

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

string get_uuid()

Return a UUID string.

unknown get_var(string varname)

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

ip4addr host_ip()

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

ip4addr host_ip(integer nth)

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

string hostname()

Return the hostname (short form).

string hostname_fqdn()

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

integer hour(datetime datetime)

Return the hour part of the time value.

integer integer(unknown arg)

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

ip4addr ip4addr(integer arg)

Convert the integer argument to an ip4addr type.

ip4addr ip4addr(integer arg, boolean ntoa)

Convert the integer argument to an ip4addr 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.

string lc(string arg)

Convert the string to lower case.

integer microsecond(datetime datetime)

Return the microsecond part of the time value.

integer minute(datetime datetime)

Return the minute part of the time value.

integer month(datetime datetime)

Return the month part of the datetime value.

datetime now()

Return the current time.

string nxlog_version()

Return the NXLog version string.

datetime parsedate(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 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
datetime parsedate(string arg, 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).

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

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

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

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

integer second(datetime datetime)

Return the second part of the time value.

integer size(string str)

Return the size of the string str in bytes.

string strftime(datetime datetime, 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).

string string(unknown arg)

Convert the argument to a string.

datetime strptime(string input, string fmt)

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

string substr(string src, integer from)

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

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

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

string type(unknown arg)

Return the type of the variable, which can be boolean, integer, string, datetime, ip4addr, ip6addr, regexp, or binary. For values with the unknown type, it returns undef.

string uc(string arg)

Convert the string to upper case.

string unescape_html(string html)

Return the HTML unescaped html string.

string unescape_json(string jsonstr)

Unescape and return jsonstr according to the JSON specification.

string unescape_url(string url)

Return the URL decoded string for url.

string unescape_xml(string xmlstr)

Return the XML unescaped xmlstr string.

integer year(datetime datetime)

Return the year part of the datetime value.

107.7. Procedures

The following procedures are exported by core.

add_stat(string statname, integer value);

Add value to the statistical counter using the current time.

add_stat(string statname, integer value, datetime time);

Add value to the statistical counter using the time specified in the argument named time.

add_to_route(string routename);

Copy the currently processed event data to the route specified. This procedure makes a copy of the data. The original will be processed normally. Note that flow control is explicitly disabled when moving data with add_to_route() and the data will not be added if the queue of the target module(s) is full.

create_stat(string statname, string type);

Create a module statistical counter with the specified name using the current time. The statistical counter will be created with an infinite lifetime. The type argument must be one of the following to select the required algorithm for calculating the value of the statistical counter: COUNT, COUNTMIN, COUNTMAX, AVG, AVGMIN, AVGMAX, RATE, RATEMIN, RATEMAX, GRAD, GRADMIN, or GRADMAX (see Statistical Counters).

This procedure with two parameters can only be used with COUNT, otherwise the interval parameter must be specified (see below). This procedure will do nothing if a counter with the specified name already exists.

create_stat(string statname, string type, integer interval);

Create a module statistical counter with the specified name to be calculated over interval seconds and using the current time. The statistical counter will be created with an infinite lifetime.

create_stat(string statname, string type, integer interval, datetime time);

Create a module statistical counter with the specified name to be calculated over interval seconds and the time value specified in the time argument. The statistical counter will be created with an infinite lifetime.

create_stat(string statname, string type, integer interval, datetime time, integer lifetime);

Create a module statistical counter with the specified name to be calculated over interval seconds and the time value specified in the time argument. The statistical counter will expire after lifetime seconds.

create_stat(string statname, string type, integer interval, datetime time, datetime expiry);

Create a module statistical counter with the specified name to be calculated over interval seconds and the time value specified in the time argument. The statistical counter will expire at expiry.

create_var(string varname);

Create a module variable with the specified name. The variable will be created with an infinite lifetime.

create_var(string varname, integer lifetime);

Create a module variable with the specified name and the lifetime given in seconds. When the lifetime expires, the variable will be deleted automatically and get_var(name) will return undef.

create_var(string varname, datetime expiry);

Create a module variable with the specified name. The expiry specifies when the variable should be deleted automatically.

debug(unknown arg, varargs args);

Print the argument(s) at DEBUG log level. Same as log_debug().

delete(unknown arg);

Delete the field from the event. For example, delete($field). Note that $field = undef is not the same, though after both operations the field will be undefined.

delete(string arg);

Delete the field from the event. For example, delete("field").

delete_all();

Delete all of the fields from the event except raw_event field.

delete_stat(string statname);

Delete a module statistical counter with the specified name. This procedure will do nothing if a counter with the specified name does not exist (e.g. was already deleted).

delete_var(string varname);

Delete the module variable with the specified name if it exists.

drop();

Drop the event record that is currently being processed. Any further action on the event record will result in a "missing logdata" error.

duplicate_guard();

Guard against event duplication.

log_debug(unknown arg, varargs args);

Print the argument(s) at DEBUG log level. Same as debug().

log_error(unknown arg, varargs args);

Print the argument(s) at ERROR log level.

log_info(unknown arg, varargs args);

Print the argument(s) at INFO log level.

log_warning(unknown arg, varargs args);

Print the argument(s) at WARNING log level.

module_restart();

Issue module_stop and then a module_start events for the calling module.

module_start();

Issue a module_start event for the calling module.

module_stop();

Issue a module_stop event for the calling module.

rename_field(unknown old, unknown new);

Rename a field. For example, rename_field($old, $new).

rename_field(string old, string new);

Rename a field. For example, rename_field("old", "new").

reroute(string routename);

Move the currently processed event data to the route specified. The event data will enter the route as if it was received by an input module there. Note that flow control is explicitly disabled when moving data with reroute() and the data will be dropped if the queue of the target module(s) is full.

set_var(string varname, unknown value);

Set the value of a module variable. If the variable does not exist, it will be created with an infinite lifetime.

sleep(integer interval);

Sleep the specified number of microseconds. This procedure is provided for testing purposes primarily. It can be used as a poor man’s rate limiting tool, though this use is not recommended.

← Previous: Configuration | ↑ Up: Enterprise Edition Reference Manual | ⌂ Home: NXLog User Guide | Next: Extension Modules →