Internal (im_internal)

NXLog Agent produces logs about its operations, such as info, warning, and error messages. This module makes it possible to insert those internal log messages into a route. Internal messages can also be generated from the NXLog language using the log_info(), log_warning(), and log_error() procedures.

The im_internal module always logs messages with log level INFO and above, independently of the LogLevel value. If necessary, you can filter the log messages explicitly using the $SeverityValue field. Debug messages are ignored due to technical reasons. For debugging purposes the direct logging facility should be used: global LogFile and LogLevel directives.

If internal messages are required in syslog format, they must be explicitly converted with the to_syslog_bsd() procedure of the xm_syslog module, because the $raw_event field is not generated in syslog format.

Careful use of the im_internal module is essential to avoid message loops and resource exhaustion. Log functions (log_info, log_warn, etc.) are intentionally blocked within the im_internal module to prevent light speed in-module recursion, which can overwhelm the system almost immediately. Additionally, out-of-module recursion—such as routing internal logs to external destinations like a database—can result in rapid log proliferation, quickly filling up disk space or network bandwidth. To mitigate these risks, NXLog strongly recommends placing the im_internal module in a separate route.

Configuration

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

Optional directives

LogqueueSize

This optional directive specifies the maximum number of internal log messages that can be queued by this module. When the queue becomes full (which can happen for example, when FlowControl is in effect), a warning will be logged, and older queued messages will be dropped in favor of new ones. The default value for this directive is inherited from the value of the global level LogqueueSize directive.

Fields

The following fields are used by im_internal.

$raw_event (type: string): A list of event fields in key-value pairs.

$ErrorCode (type: integer): The error number provided by the Apache portable runtime library, if an error is logged resulting from an operating system error.

$EventTime (type: datetime): The current time.

$Hostname (type: string): The hostname where the log was produced.

$Message (type: string): The same value as $raw_event.

$ModuleName (type: string): The name of the module instance which generated the internal log event. Not to be confused with $SourceModuleName, which will identify the current im_internal instance.

$ModuleType (type: string): The type of the module (such as im_file) which generated the internal log event. Not to be confused with $SourceModuleType, which will be im_internal.

$ProcessID (type: integer): The process ID of the NXLog Agent process.

$Severity (type: string): The severity of the internal event. Possible values are INFO, WARNING, ERROR, or CRITICAL.

$SeverityValue (type: integer): The numerical value corresponding to the severity of the internal event. Possible values are 2 (INFO), 3 (WARNING), 4 (ERROR), or 5 (CRITICAL).

$SourceName (type: string): Set to nxlog.

Examples

Example 1. Forwarding Internal Messages over syslog UDP

This configuration collects NXLog Agent internal messages that have a severity level of at least 4 (corresponding to the severities ERROR and CRITICAL), adds BSD syslog headers, and forwards them via UDP.

nxlog.conf

<Extension syslog>
    Module  xm_syslog
</Extension>

<Input internal>
    Module  im_internal
    <Exec>
        if ( $SeverityValue < 4 )
            drop();
    </Exec>
</Input>

<Output udp>
    Module  om_udp
    Host    192.168.1.1:514
    Exec    to_syslog_bsd();
</Output>

<Route internal_to_udp>
    Path    internal => udp
</Route>