NXLog Docs

Internal (im_internal)

NXLog produces its own logs about its operations, including errors and debug 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.

Only messages with log level INFO and above are supported. Debug messages are ignored due to technical reasons. For debugging purposes the direct logging facility should be used: see the global LogFile and LogLevel directives.

One must be careful about the use of the im_internal module because it is easy to cause message loops. For example, consider the situation when internal log messages are sent to a database. If the database is experiencing errors which result in internal error messages, then these are again routed to the database and this will trigger further error messages, resulting in a loop. In order to avoid a resource exhaustion, the im_internal module will drop its messages when the queue of the next module in the route is full. It is recommended to always put the im_internal module instance in a separate route.

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

Configuration

The im_internal module accepts the following directive in addition to the common module 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 process.

$Severity (type: string): The severity name of the event.

$SeverityValue (type: integer): Depending on the log level of the internal message, the value corresponding to "debug", "info", "warning", "error", or "critical".

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

Examples

Example 1. Forwarding Internal Messages over syslog UDP

This configuration collects NXLog internal messages, adds BSD syslog headers, and forwards via UDP.

nxlog.conf

<Extension syslog>
    Module  xm_syslog
</Extension>

<Input internal>
    Module  im_internal
</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>