Package com.ibm.streams.operator.logging
See: Description
-
Interface Summary Interface Description LoggerNames Names for instances ofjava.util.logging.Loggerwith a specific purpose for the Java Operator API. -
Class Summary Class Description LogLevel Convenience class to provide SPL log levels through thejava.util.loggingfacility.TraceLevel Convenience class to provide SPL trace levels through thejava.util.loggingfacility.
Package com.ibm.streams.operator.logging Description
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 SPL log facility maps to the target use
problem diagnosis by end users and system administrators
described by java.util.Logging.
The java.util.logging.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 standard Java java.util.logging.Level values
and SPL log levels.
This Logger accepts any Level but any log messages at a level
below LogLevel.INFO (equals to Level.CONFIG) 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 SPL trace facility maps to the target use
problem diagnosis by field service engineers,
problem diagnosis by the development organization and
problem diagnosis by developers
described by java.util.Logging.
The root java.util.logging.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 anonymous Logger
and any named Logger not in the com.ibm.streams.operator.log name space
will deliver messages to the SPL trace facility.
When running in an InfoSphere® Streams distributed or standalone
application the root java.util.logging.Logger has a java.util.logging.Handler
that sends messages to the SPL trace facility.
The level of the handler and root logger are set to 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
TraceLevel provides Java values for SPL trace levels
and also describes the mapping between standard Java java.util.logging.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.
Message Formatting
The root and com.ibm.streams.operator.log Logger use a plain formatter that
formats the message using java.util.logging.Formatter.formatMessage(). The resultant
message is passed 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 create a Logger with a ResourceBundle
to be used for localizing messages. Typically the resource bundles (message files) will be in the
jar files containing the operator or library classes.
- Since:
- InfoSphere® Streams Version 3.0