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. For information about how to parse message catalogs to validate and generate classes used for localizing text in log messages, see Developing Applications for Event Processing with Oracle Stream Analytics.
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 Stream Analytics 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 Stream Analytics 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 Stream Analytics 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 Stream Analytics 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 Stream Analytics 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.
For more information on configuring logging using Oracle Stream Analytics Visualizer, see Using Visualizer for Oracle Stream Analytics.
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 Stream Analytics can specify their logging severity. This severity overrides the default logging severity of the Oracle Stream Analytics server.
You do this by specifying an entry
child element in the logger-severity-properties
element in the Oracle Stream Analytics server config.xml
file. You can specify multiple entry
child elements for any number of modules.
Configure Severity for an Individual Module
Oracle Stream Analytics 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 Stream Analytics applications to log application-specific messages to the Oracle Stream Analytics 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 Stream Analytics applications.
Table 14-6 lists the debugging options that Oracle Stream Analytics 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 Stream Analytics debugging options:
If you are using Log4j logging, see also Debug Log4j Logging.
Use the following steps to configure debugging using system properties.
In this procedure, you will turn on Simple Declarative Services (SDS) debugging (com.bea.core.debug.DebugSDS
from Table 14-6) using the Oracle Stream Analytics server startwlevs.sh
file.
Configure Debugging Options using System Properties
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 Stream Analytics server config.xml
file.
Configure Debugging Options with a Configuration File