System administrators and developers configure logging output and filter log messages to troubleshoot errors or to receive notification for specific events.
Oracle Stream Analytics supports the Commons Apache Logging Framework, OSGi Framework Logger, and Log4j Logger logging systems. Oracle Stream Analytics also provides a variety of debugging options that you can enable and disable to help diagnose your Oracle Stream Analytics applications.
This chapter includes the following sections:
For information about Oracle Stream Analytics security auditor logging, see Security Auditor.
There are various logging configuration scenarios. Some of the common ones are listed here.
Stop DEBUG and INFO messages from going to the log file.
Allow INFO level messages from the HTTP subsystem to be published to the log file, but not to standard out.
Specify that a handler publishes messages that are WARNING level or higher.
Specify a default logging level for the entire server, and have a specific module override the default logging level. For example, the default logging level of the server could be WARNING while the logging level of the module is DEBUG.
Configure a logging level for a deployed application. The application must use the Commons Apache Logging Framework if it is required to output log messages to the single server-wide log file to which server modules also log their messages.
This section explains the commons Apache logging framework.
Oracle Event Processing provides a commons-logging interface. The interface provides commons.logging.LogFactory and Log interface implementations. It includes an extension of the org.apache.commons.logging.LogFactory class that acts as a factory to create an implementation of the org.apache.commons.logging.Log that delegates to the LoggingService in the logging module. The name of this default implementation is weblogic.logging.commons.LogFactoryImpl. See http://jakarta.apache.org/commons/logging/apidocs/index.html.
The following list provides information about setting the log factory using system properties:
The highest priority is given to the system property org.apache.commons.logging.LogFactory.
You can set logging from the command line using:
-Dorg.apache.commons.logging.LogFactory=weblogic.logging.commons.LogFactoryImpl
You can programmatically implement the logging by:
import org.apache.commons.logging.LogFactory;
System.setProperty(
LogFactory.FACTORY_PROPERTY,
"weblogic.logging.commons.LogFactoryImpl"
);
The weblogic.logging.commons.LogFactoryImpl is the default log factory, if not explicitly set.
To use another logging implementation, you must use the standard commons logging factory implementation. The org.apache.commons.logging.impl.LogFactoryImpl implementation is available in the commons logging jar. For example:
-Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl
or the equivalent programming would be:
System.setProperty(
LogFactory.FACTORY_PROPERTY,
"org.apache.commons.logging.impl.LogFactoryImpl"
);
Each log message has an associated severity level. The level gives a rough guide to the importance and urgency of a log message. Predefined severities, ranging from TRACE to EMERGENCY, are converted to a log level when dispatching a log request to the logger. A log level object can specify any of the following values, from lowest (left-most) to highest (right-most) impact:
TRACE, DEBUG, INFO, NOTICE, WARNING, ERROR, CRITICAL, ALERT, EMERGENCY
You can set a log severity level on the logger, the handler, and a user application. When set on the logger, none of the handlers receive an event which is rejected by the logger. For example, if you set the log level to NOTICE on the logger, none of the handlers will receive INFO level events. When you set a log level on the handler, the restriction only applies to that handler and not the others. For example, turning DEBUG off for the File Handler means no DEBUG messages will be written to the log file, however, DEBUG messages will be written to standard out.
Users (Oracle Event Processing module owners or owners of user applications) are free to define the names that represent the logging category type used by the Apache commons logging for individual modules. However if the category names are defined as package names then based on the naming convention, a logging level hierarchy is assumed by default. For example, if two modules name their logging category names com.oracle.foo and com.oracle.foo.bar, then com.oracle.foo becomes the root node of com.oracle.foo.bar. This way any logging level applied to parent node (com.oracle.foo) automatically applies to com.oracle.foo.bar, unless the child node overrides the parent.
In other words, if the logging severity is specified for a node, it is effective unless the severity is inherited from the nearest parent whose severity is explicitly configured. The root node is always explicitly configured, so if nothing else if set, then all the nodes inherit the severity from the root.
Table 14-1 lists the severity levels of log messages.
Table 14-1 Log Message Severity
| Severity | Meaning |
|---|---|
TRACE |
Used for messages from the Diagnostic Action Library. Upon enabling diagnostic instrumentation of server and application classes, |
DEBUG |
A debug message was generated. |
INFO |
Used for reporting normal operations, a low-level informational message. |
NOTICE |
An informational message with a higher level of importance. |
WARNING |
A suspicious operation or configuration has occurred but it might not affect normal operation. |
ERROR |
A user error has occurred. The system or application can handle the error with no interruption and limited degradation of service. |
CRITICAL |
A system or service error has occurred. The system can recover but there might be a momentary loss or permanent degradation of service. |
ALERT |
A particular service is in an unusable state while other parts of the system continue to function. Automatic recovery is not possible; the immediate attention of the administrator is needed to resolve the problem. |
EMERGENCY |
The server is in an unusable state. This severity indicates a severe system failure or panic. |
The system generates many messages of lower severity and fewer messages of higher severity. For example, under normal circumstances, they generate many INFO messages and no EMERGENCY messages.
By default, Oracle Event Processing server writes log messages to the server.log and consoleoutput.log files in the /Oracle/Middleware/my_oep/user_projects/domains/DOMAIN_DIR/servername directory, where DOMAIN_DIR refers to the domain directory (such as my_domain), and servername refers to the server instance directory (such as myServer1).
For information on configuring log file attributes, see log-file.
Oracle Event Processing server writes log messages in different formats depending on the type of log file it is writing to.
The system writes a message to the specified log file consisting of a #### prefix, Timestamp, Severity, Subsystem, Server Name, Connection, Thread ID or User ID or Transaction ID, Message ID, and the Message, along with a stack trace if any. Each attribute is contained between angle brackets.
The following is an example of a message in the server log file (split for readability; in practice, the message might be on one line):
####<May 25, 2015 10:23:32 AM EST> <Notice> <Deployment> <> <myServer> <RMI TCP Connection(4)-141.144.123.236> <> <> <> <1235575412801> <BEA-2045000> <The application bundle "Hello" was deployed successfully to file [C:\Oracle\Middleware\my_oep\user_projects\domains\oep_domain\defaultserver\applications\Hello\Hello.jar] with version 1235575412708>
The system writes a message to the console, standard out, or standard error consisting of Locale-formatted Timestamp, Severity, Subsystem, Message ID, and Message.
The following is an example of how the message from the previous section would be printed to standard out (split for readability; in practice, the message might be on one line):
<May 25, 2015 10:23:32 AM EST> <Notice> <Deployment> <BEA-2045000> <The application bundle "Hello" was deployed successfully to file [C:\Oracle\Middleware\my_oep\user_projects\domains\oep_domain\defaultserver\applications\Hello\Hello.jar] with version 1235575412708>
Oracle Event Processing has a low-level framework logger that is started before the OSGi framework. It is used to report logging event deep inside the OSGi framework and function as a custom default for the logging subsystem before it is configured.
For example, a user may see some log message, which has lower level or severity than what is set in the config.xml but higher or equal to what is set on the Launcher command line on the console or in the log file. Until the logging subsystem has started, log messages come from the framework logger and use the framework logging level to filter messages.
Log4j is an open source tool developed for putting log statements in your application. Log4j has three main components: loggers, appenders, and layouts, which are all described in this section.
The Log4j Java logging facility was developed by the Jakarta Project of the Apache Foundation. See:
The Log4j Project at http://logging.apache.org/log4j/.
The Log4j API at http://logging.apache.org/log4j/1.2/apidocs/index.html.
Short introduction to log4j at http://logging.apache.org/log4j/1.2/manual.html.
Log4j defines a Logger class. An application can create multiple loggers, each with a unique name. In a typical usage of Log4j, an application creates a Logger instance for each application class that will emit log messages. Loggers exist in a name space hierarchy and inherit behavior from their ancestors in the hierarchy.
Log4j defines appenders (handlers) to represent destinations for logging output. Multiple appenders can be defined. For example, an application might define an appender that sends log messages to standard out, and another appender that writes log messages to a file. Individual loggers might be configured to write to zero or more appenders. One example usage would be to send all logging messages (all levels) to a log file, but only ERROR level messages to standard out.
You configure Oracle Stream Analytics logging service attributes using Oracle Stream Analytics Visualizer or by editing the Oracle Stream Analytics server config.xml file.
The config.xml file is located in the /Oracle/Middleware/my_oep/user_projects/domains/DOMAIN_DIR/servername/config directory, where DOMAIN_DIR refers to the domain directory (such as my_domain), and servername refers to the server instance directory (such as myServer1).
The following example shows a typical Oracle Stream Analytics server config.xml file with logging elements.
<?xml version="1.0" encoding="UTF-8"?>
<!--Sample XML file generated by XMLSpy v2007 sp2 (http://www.altova.com)-->
<n1:config
xsi:schemaLocation="http://www.bea.com/ns/wlevs/config/server wlevs_server_config.xsd"
xmlns:n1="http://www.bea.com/ns/wlevs/config/server"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...
<name>myLogService</name>
<log-file-config>myFileConfig</log-file-config>
<stdout-config>myStdoutConfig</stdout-config>
<logger-severity>Notice</logger-severity>
<logger-severity-properties>
<entry>
<key>LifeCycle</key>
<value>Notice</value>
</entry>
<entry>
<key>Management</key>
<value>Notice</value>
</entry>
<entry>
<key>CQLProcessor</key>
<value>Notice</value>
</entry>
<entry>
<key>CqlProcessor</key>
<value>Notice</value>
</entry>
<entry>
<key>Stream</key>
<value>Notice</value>
</entry>
<entry>
<key>Ede</key>
<value>Notice</value>
</entry>
<entry>
<key>Cache</key>
<value>Notice</value>
</entry>
<entry>
<key>Adapters</key>
<value>Notice</value>
</entry>
<entry>
<key>Spring</key>
<value>Notice</value>
</entry>
<entry>
<key>Channel</key>
<value>Notice</value>
</entry>
<entry>
<key>Recplay</key>
<value>Notice</value>
</entry>
<entry>
<key>Monitor</key>
<value>Notice</value>
</entry>
<entry>
<key>Server</key>
<value>Notice</value>
</entry>
<entry>
<key>EventTrace</key>
<value>Notice</value>
</entry>
<entry>
<key>Deployment</key>
<value>Notice</value>
</entry>
</logger-severity-properties>
</logging-service>
<log-file>
<name>myFileConfig</name>
<rotation-type>none</rotation-type>
</log-file>
<log-stdout>
<name>myStdoutConfig</name>
<stdout-severity>Debug</stdout-severity>
</log-stdout>
</n1:config>
The following sections provide information on configuring Oracle Stream Analytics logging:
This section provides information on the logging-service element:
Table 14-2 Configuration Parameters for logging-service
| Parameter | Type | Description |
|---|---|---|
name |
String |
The name of this configuration object. |
log-file-config |
String |
The configuration of the log file and its rotation policies. See log-file. |
stdout-config |
String |
The name of the |
logger-severity |
String |
Defines the threshold importance of the messages that are propagated to the handlers. The default value is To see Valid values are: |
logger-severity-properties |
One or more |
List of name-value pairs, enclosed in an |
This section provides information on the log-file element:
Table 14-3 Configuration Parameters for log-file
| Parameter | Type | Description |
|---|---|---|
name |
String |
The name of this configuration object. |
base-log-file-name |
String |
The log file name. Default value is |
log-file-severity |
String |
Specifies the least important severity of messages written to the log file. Default value is Valid values are:
|
log-file-rotation-dir |
String |
Specifies the directory where old rotated files are stored. If not set, the old files are stored in the same directory as the base log file. |
rotation-type |
String |
Specifies how rotation is performed based on size, time, or not at all. Valid values are:
|
rotation-time |
String |
The time in Default is |
rotation-time-span-factor |
Long |
Factor applied to the timespan to determine the number of milliseconds that becomes the frequency of time based log rotations. Default is |
rotated-file-count |
Integer |
Specifies the number of old rotated files to keep if |
rotation-size |
Integer |
The size threshold, in KB, at which the log file is rotated. Default is |
rotation-time-span |
Integer |
Specifies the interval for every time-based log rotation. Default value is |
rotate-log-on-startup-enabled |
Boolean |
If |
number-of-files-limited |
Boolean |
If |
This section provides information on the log-stdout element:
Table 14-4 Configuration Parameters for log-stdout
| Parameter | Type | Description |
|---|---|---|
name |
String |
The name of this configuration object. |
stdout-severity |
String |
The threshold severity for messages sent to stdout. Default value is Valid values are:
|
stack-trace-depth |
Integer |
The number of stack trace frames to display on stdout. A default value of |
stack-trace-enabled |
Boolean |
If true, stack traces are dumped to the console when included in logged messages. Default value is |
Individual modules of Oracle Event Processing can specify their logging severity. This severity overrides the default logging severity of the Oracle Event Processing server.
You do this by specifying an entry child element in the logger-severity-properties element in the Oracle Event Processing server config.xml file. You can specify multiple entry child elements for any number of modules.
Configure Severity for an Individual Module
Oracle Event Processing supports the open-source log4j logging system.
This section describes the following tasks:
The default configuration file is log4j.properties. It can be overridden by using the log4j.configuration system property. See https://www.qos.ch/shop/products/log4j/log4j-Manual.jsp.
The following is an example of a log4j.properties file:
log4j.rootLogger=debug, R log4j.appender.R=org.apache.log4j.RollingFileAppender log4j.appender.R.File=D:/log4j/logs/mywebapp.log log4j.appender.R.MaxFileSize=10MB log4j.appender.R.MaxBackupIndex=10 log4j.appender.R.layout=org.apache.log4j.PatternLayout log4j.appender.R.layout.ConversionPattern=%p %t %c - %m%n log4j.logger=DEBUG, R
Update the MANIFEST.MF file of your application to import the following required Log4j packages.
Import-Package:
org.apache.log4j;version="1.2.13",
org.apache.log4j.config;version="1.2.13",
...
To specify logging to a Log4j Logger, set the following system properties on the command line:
-Dorg.apache.commons.logging.LogFactory=org.apache.commons.logging.impl.LogFactoryImpl -Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger -Dlog4j.configuration=<URL>/log4j.properties
Another very useful command line property is -Dlog4j.debug=true. Use this property when log4j output fails to appear or you get cryptic error messages.
If log4j output fails to appear or you get cryptic error messages, consider using the command line property -Dlog4j.debug=true on the command line.
For more information, see Enable Log4j Logging.
You can use Apache Commons logging API in your Oracle Event Processing applications to log application-specific messages to the Oracle Event Processing server.log and consoleoutput.log files.
To use the commons logging API:
import org.apache.commons.logging.LogFactory;
import org.apache.commons.logging.Log;
public class MyCommonsTest {
public void testCommonsLogging() {
System.setProperty(LogFactory.FACTORY_PROPERTY,
"weblogic.logging.commons.LogFactoryImpl");
Log clog = LogFactory.getFactory().getInstance("MyCommonsLogger");
// Log String objects
clog.debug("Hey this is common debug");
clog.fatal("Hey this is common fatal", new Exception());
clog.error("Hey this is common error", new Exception());
clog.trace("Dont leave your footprints on the sands of time");
}
}
You can enable and disable debugging options to help diagnose problems with your Oracle Event Processing applications.
Table 14-6 lists the debugging options that Oracle Event Processing provides.
Table 14-6 Debug Flags
| Debug Flag | Description |
|---|---|
com.bea.core.debug.DebugBootBundle |
Boot Debugging |
com.bea.core.debug.DebugBootBundle.stdout |
Boot Debugging debug strings go to stdout |
com.bea.core.debug.DebugCM |
Configuration Manager |
com.bea.core.debug.DebugCM.stdout |
Configuration Manager debug strings go to stdout |
com.bea.core.debug.DebugConfigurationRuntime |
Runtime information from the Runtime MBeans |
com.bea.core.debug.DebugCSS |
CSS |
com.bea.core.debug.DebugCSS.stdout |
CSS debug strings go to stdout |
com.bea.core.debug.DebugCSSServices |
CSS Services |
com.bea.core.debug.DebugCSSServices.stdout |
CSS Services debug strings go to stdout |
com.bea.core.debug.DebugJDBCConn |
JDBC Connection |
com.bea.core.debug.DebugJDBCInternal |
JDBC Internal |
com.bea.core.debug.DebugJDBCRMI |
JDBC RMI |
com.bea.core.debug.DebugJDBCSQL |
JDBC SQL |
com.bea.core.debug.DebugJTA2PC |
JTA 2PC |
com.bea.core.debug.DebugJTA2PCDetail |
JTA 2PCDetail |
com.bea.core.debug.DebugJTA2PCStackTrace |
JTA 2PCStackTrace |
com.bea.core.debug.DebugJTAGateway |
JTA Gateway |
com.bea.core.debug.DebugJTAGatewayStackTrace |
JTA GatewayStackTrace |
com.bea.core.debug.DebugJTAHealth |
JTA Health |
com.bea.core.debug.DebugJTAJDBC |
JTA JDBC |
com.bea.core.debug.DebugJTALifecycle |
JTA Lifecycle |
com.bea.core.debug.DebugJTALLR |
JTA LLR |
com.bea.core.debug.DebugJTAMigration |
JTA Migration |
com.bea.core.debug.DebugJTANaming |
JTA Naming |
com.bea.core.debug.DebugJTANamingStackTrace |
JTA NamingStackTrace |
com.bea.core.debug.DebugJTANonXA |
JTA NonXA |
com.bea.core.debug.DebugJTAPropagate |
JTA Propagate |
com.bea.core.debug.DebugJTARecovery |
JTA Recovery |
com.bea.core.debug.DebugJTAResourceHealth |
JTA ResourceHealth |
com.bea.core.debug.DebugJTATLOG |
JTA TLOG |
com.bea.core.debug.DebugJTAXA |
JTA XA |
com.bea.core.debug.DebugJTAXAStackTrace |
JTA XAStackTrace |
com.bea.core.debug.DebugNetIO |
NetIO |
com.bea.core.debug.DebugOX |
OSGi to JMX (OX) |
com.bea.core.debug.DebugOX.stdout |
OSGi to JMX (OX), debug goes to standard out. |
com.bea.core.debug.DebugSCP |
Simple Configuration Provider |
com.bea.core.debug.DebugSCP.stdout |
Simple Configuration Provider debug strings go to stdout |
com.bea.core.debug.DebugSDS |
Simple Declarative Services |
com.bea.core.debug.DebugSDS.stdout |
SDS debug strings go to stdout |
com.bea.core.debug.DebugServiceHelper |
Service Helper |
com.bea.core.debug.DebugServiceHelper.stdout |
Service Helper debug strings go to stdout |
com.bea.core.debug.DebugStoreAdmin |
Store Administration |
com.bea.core.debug.DebugStoreIOLogical |
Store IOLogical |
com.bea.core.debug.DebugStoreIOLogicalBoot |
Store IOLogicalBoot |
com.bea.core.debug.DebugStoreIOPhysical |
Store IOPhysical |
com.bea.core.debug.DebugStoreIOPhysicalVerbose |
Store IOPhysicalVerbose |
com.bea.core.debug.DebugStoreXA |
Store XA |
com.bea.core.debug.DebugStoreXAVerbose |
Store XAVerbose |
com.bea.core.debug.servicehelper.dumpstack |
Dump stack traces when Service Helper times out. |
The following sections provide information on how to use these Oracle Event Processing debugging options:
If you are using Log4j logging, see also Debug Log4j Logging.
This section describes the procedure to configure debugging options with a Configuration File.
Use the following steps to configure debugging from a configuration file.
In this procedure, you will turn on Simple Declarative Services (SDS) debugging (com.bea.core.debug.DebugSDS from Table 14-6) in the Oracle Event Processing server config.xml file.
Configure Debugging Options with a Configuration File