Apama 10.15.0 | Deploying and Managing Apama Applications | Correlator Utilities Reference | Shutting down and managing components | Setting EPL log files and log levels dynamically
 
Setting EPL log files and log levels dynamically
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 files and log levels in a YAML configuration file.
You can configure per-package logging in several ways:
*Dynamically, using the following options of the engine_management tool as described in this topic:
--setApplicationLogFile
--setApplicationLogLevel
*Statically, in a YAML configuration file when starting the correlator. See Setting EPL log files and log levels in a YAML configuration file for detailed information.
*Dynamically from within EPL. See Using the Management interface for detailed information.
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.
Note: 
Regularly rotating log files and storing the old ones in a secure location may be important as part of your personal data protection policy. For more information, see Recommendations for logging by Apama application code.
Tree structure of packages, monitors, and events
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.
Illustration of the tree structure
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.
Managing EPL log levels
To set the log level for a package, monitor or event, invoke the engine_management tool as follows:
engine_management --setApplicationLogLevel [node=]logLevel
Option
Description
node
Optionally, specify the name of a package, monitor or event. If you do not specify a node name, the tool sets the log level for the default package.
logLevel
Specify OFF, CRIT, FATAL, ERROR, WARN, INFO, DEBUG, or TRACE.
To obtain the log level for a particular node, invoke the tool as follows:
engine_management --getApplicationLogLevel [node]
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.
engine_management --unsetApplicationLogLevel [node]
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.
Log level in effect
Log statements with these identifiers go to the appropriate log file
Log statements with these identifiers are ignored
OFF
None
CRIT, FATAL, ERROR, WARN, INFO, DEBUG, TRACE
CRIT
CRIT
FATAL, ERROR, WARN, INFO, DEBUG, TRACE
FATAL
CRIT, FATAL
ERROR, WARN, INFO, DEBUG, TRACE
ERROR
CRIT, FATAL, ERROR
WARN, INFO, DEBUG, TRACE
WARN
CRIT, FATAL, ERROR, WARN
INFO, DEBUG, TRACE
INFO
CRIT, FATAL, ERROR, WARN, INFO
DEBUG, TRACE
DEBUG
CRIT, FATAL, ERROR, WARN, INFO, DEBUG
TRACE
TRACE
CRIT, FATAL, ERROR, WARN, INFO, DEBUG, TRACE
None
See also Log levels determine results of log statements.
Managing EPL log files
To specify a log file for a package, monitor or event, invoke the engine_management tool as follows:
engine_management --setApplicationLogFile [node=]logFile
Option
Description
node
Optionally, specify the name of a package, monitor or event. If you do not specify a node name, the tool associates the log file with the default package.
logFile
Specify the path of the log file. You specify the name of an EPL log file in the same way that you specify the name of a main correlator log file or input log file. See Specifying log filenames.
To obtain the path of the log file for a particular node, invoke the tool as follows:
engine_management --getApplicationLogFile [node]
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.
engine_management --unsetApplicationLogFile [node]
Managing event logging attributes
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:
engine_management --setApplicationLogFile NestedEventType=foo.log
engine_management --setApplicationLogLevel NestedEventType=DEBUG