Package com.ibm.streams.operator.log4j

SPL trace and logging for the Java Operator API using the Apache log4j logging facilities.

See: Description

  • Interface Summary 
    Interface Description
    LoggerNames
    Apache log4j Logger names with a specific purpose for Java operators.
  • Class Summary 
    Class Description
    LogLevel
    Convenience class to provide SPL log levels through the org.apache.log4j facility.
    TraceLevel
    Convenience class to provide SPL trace levels through the org.apache.log4j facility.

Package com.ibm.streams.operator.log4j Description

SPL trace and logging for the Java Operator API using the Apache log4j logging facilities. The SPL Runtime provides Apache log4j version 1.2.16.

SPL Log Facility - com.ibm.streams.operator.log Logger

The SPL log facility is for application logging, where logging is defined as the recording of serviceability information pertaining to application or operator events. The purpose of logging is to provide an administrator with enough information to do problem determination for items they can potentially control. In general, very few events are logged in the normal running scenario of an application or operator. Events pertinent to the failure or partial failure of application runtime scenarios should be logged.

The org.apache.log4j.Logger named com.ibm.streams.operator.log delivers log messages to the SPL log facility. LogLevel provides Java values for SPL log levels and also describes the mapping between Apache log4j org.apache.log4j.Level values and SPL log levels.
This Logger accepts any Level but any log messages at a level below LogLevel.INFO (equals to Level.INFO) are sent to the SPL trace facility. It is recommended however that for code clarity, tracing within an operator does not use this Logger but instead uses one that maps to the SPL trace facility.

Operators may create their own loggers that are children of the com.ibm.streams.operator.log Logger by creating one in a child name space, such as com.ibm.streams.operator.log.com.example.operators.myoperator.

SPL Trace Facility - Root Logger

The SPL trace facility is for application tracing, where tracing is defined as the recording of application or operator internal events and data. The purpose of tracing is to allow SPL application or operator developers to debug their applications or operators.

The root org.apache.log4j.Logger for the core logging facility delivers messages to the SPL trace facility, and thus any child Logger will also deliver messages to the SPL trace facility. This means that any named Logger not in the com.ibm.streams.operator.log name space will deliver messages to the SPL trace facility.

When running in as an InfoSphere® Streams distributed or standalone application the root org.apache.log4j.Logger has a org.apache.log4j.Appender that sends messages to the SPL trace facility. The level of the appender and root logger are set the the SPL tracing level of the processing element and are dynamically updated when the trace level is updated. The trace level for a processing element may be updated from the command line using:
streamtool updatepe -i instanceId --pes peId --config tracing=level

Dynamic configuration of Apache Log4j loggers is supported so that fine grained trace can be enabled on a per-logger basis during runtime. The configuration file log4j.properties in the application's data directory is used to update the Apache Logj configuration. If this file exists and is readable by the instance owner then the configuration is updated:

  • When the processing element starts
    • .
  • When the SPL tracing level is updated using streamtool updatepe. The file can be created any time after startup.
The format of log4j.properties is described in the Apache Log4j javadoc by the method org.apache.log4j.PropertyConfigurator.doConfigure().
For example with a set of Java operators using loggers in the name space com.example.javaop then tracing could be limited to a single operator using a logger named com.example.javaop.text.TextExtractOp using this log4j.properties: 

# Disable tracing using the parent of loggers for my operators
log4j.logger.com.example.javaop=OFF
# Override the parent to have specific tracing for
# com.example.javaop.text.TextExtractOp
log4j.logger.com.example.javaop.text.TextExtractOp=TRACE

It is not recommended to dynamically change the level of the root or com.ibm.streams.operator.log loggers.

TraceLevel provides Java values for SPL trace levels and also describes the mapping between standard Java org.apache.log4j.Level values and SPL trace levels.

Logger Levels

Setting the level of any Logger using Logger.setLevel() does not change the SPL log or trace level. Such a change only affects that specific logger, typically this would be used to provide a subset of the current SPL trace level for specific components, while providing detailed trace for others at the current SPL trace level.
Operator implementations must not change the level of either the root or com.ibm.streams.operator.log loggers.

Operator implementations can be notified of a change in the SPL trace level using the ProcessingElementMXBean.TRACE_LEVEL notification. This notification can be used to change the level of an loggers or appenders to match the SPL trace level if required.

Message Formatting

The root and com.ibm.streams.operator.log Loggers have appenders that passed the rendered string directly to the SPL log or trace facility (using UTF-8 encoding) where additional formatting (e.g. adding a time stamp) is added before it is written out.

Message Localization

An operator or library called by an operator may associate a Logger with a ResourceBundle to be used for localizing messages, by using the setResourceBundle method. Typically the resource bundles (message files) will be in the jar files containing the operator or library classes. The Logger.l7dlog methods utilize the ResourceBundle associated with the Logger.

Since:
InfoSphere® Streams Version 3.0