This topic describes how to configure logging for individual EPL packages. It applies to the correlator only. For information about configuring the log level of the whole correlator and plug-ins running inside it, see Setting correlator and plug-in log levels in a YAML configuration file.

You can configure per-package logging in several ways:

In EPL code, you can specify log statements as a development or debug tool. By default, log statements that you specify in EPL send information to the correlator log file. If a log file was not specified when the correlator was started, and you have not executed the engine_management tool to associate a log file with the correlator, log statements send output to stdout.

In place of this default behavior, you can specify different log files for individual packages, monitors and events. This can be helpful during development. For example, you can specify a separate log file for a package or monitor you are implementing, and direct log output from only your development code to that file.

Also, you can specify a particular log level for a package, monitor, or event. The settings of log files and log levels are independent of each other. That is, you can set only a log level for a particular package, monitor or event, or you can set only a log level for a particular element. The topics below provide information for managing individual log files and log levels.

See also Rotating correlator log files.

Packages, monitors and events form a tree as illustrated in the figure below. For each node in the tree, you can specify a log file and/or a log level. Nodes for which you do not specify log settings inherit log settings from their parent node.

The root of the tree is the default package, which contains code that does not explicitly specify a package with the package statement. Specified packages are intermediate nodes. Packages can nest inside each other. Monitors and events in specified packages are leaf nodes. If you specify an event type in a monitor, that event is a leaf node and its containing monitor is an intermediate node.

For example, suppose you specify packageA.log as the log file for packageA. The packageA.log file receives output from log statements in MonitorE and MonitorK. If EventF contains any action members that specify log statements, output would go to the packageA.log file.

Now suppose that you set ERROR as the log level for the default package and you set INFO as the log level for PackageB. For log statements in MonitorG, PackageH, and MonitorL, the correlator compares the log statement's log level with INFO. For log statements in the rest of the tree, the correlator compares the log statement's log level with ERROR. For details, see the table in Managing EPL log levels.

To set the log level for a package, monitor or event, invoke the engine_management tool as follows:

To obtain the log level for a particular node, invoke the tool as follows:

If you do not specify a node, the tool returns the log level for the default package. To remove the log level for a node, so that it takes on the log level of its parent node, invoke the tool as follows. Again, if you do not specify a node, you remove the log level for the default package. The default package then takes on the log level in effect for the correlator. The default correlator log level is INFO.

To manage the log level for an event that you define in a monitor, see Managing event logging attributes.

After the correlator identifies the applicable log level, the log level itself determines whether the correlator sends the log statement output to the appropriate log file. The following table indicates which log level identifiers cause the correlator to send the log statement to the appropriate log file.

See also Log levels determine results of log statements.

To specify a log file for a package, monitor or event, invoke the engine_management tool as follows:

To obtain the path of the log file for a particular node, invoke the tool as follows:

If you do not specify a node, the tool returns the log file for the default package. To disassociate a log file from its node, so that the node uses the log file of its parent node, invoke the tool as follows. Again, if you do not specify a node, you disassociate the log file from the default package. The correlator log file is then in effect for the default package. If a log file has not been specified for the correlator, the default is stdout.

If you specify an event type in a monitor, that event does not inherit the logging configuration from the enclosing monitor. It is expected that this will change in a future release. To explicitly set logging attributes for an event type defined in a monitor, invoke the engine_management tool and specify an unqualified event type name. Do not specify an enclosing scope, such as com.apamax.myMonitor.NestedEventType. For example: