Starting with release 6.0, the StreamBase Java API uses slf4j, the Simple Logging Facade for Java, for all internal logging. StreamBase Systems encourages customers to use the same logging system when developing your custom embedded Java adapters and Java operators.
slf4j is a successor project to Log4J and is written by the same team. It offers a front-end facade for various Java logging system back ends that can be loaded at deployment time. slf4j supports JDK 1.4 Logging, Log4J, and Logback, among other systems. By default, the StreamBase Java API uses the Logback back end for slf4j.
In the StreamBase Java API, the base class, Operator, for Java operators and embedded adapters provides a
convenience method getLogger(). This returns an
org.slf4j.Logger object that should thereafter be used
for logging messages and exceptions in your code. The existing logError() method from previous StreamBase releases
and other convenience methods have been deprecated. StreamBase Systems
recommends replacing all instances of logError() in
your existing StreamBase Java code.
Replace instances of logError() with calls to
comparable logging methods on the Logger object returned
by Operator.getLogger(). For the full list of methods
available on Logger objects, refer to the Logger class in
the slf4j Javadoc.
Code generated by the StreamBase Java code generation wizards includes
examples of calling and using getLogger().
Note
The StreamBase Java API has internal methods with names such as
logError() and fatalError(). These are not part
of the public API, and should not be called by end users.
StreamBase Studio bundles the Javadoc for the Logger class so that when you are typing Java code in a Studio
editor, you see code assistance popups to help you understand the methods available
for logging.
Do not confuse the Java logging facility discussed here with the StreamBase error stream feature. Logging is for writing your own logging messages and exception stack traces to the log. By contrast, the error stream feature is like a module-level throw that ascends up the call stack to the containing application, and from there to the StreamBase Server instance running the application. To send an error to the error stream, you only need to throw an exception during a tuple processing method. See Using Error Ports and Error Streams for more information.
The default logging setup can be configured with environment variables or Java system properties. If both an environment variable and system property are specified, the system property takes precedence. The settings are shown in the following table.
| Environment Variable | Java Property | Default Value | Description |
|---|---|---|---|
STREAMBASE_LOG_PATTERN
|
streambase.log-pattern |
%d{yyyy-MM-dd HH:mm:ss.SSSZ} [%thread] %-5level
%logger{36} - %msg%n
|
Controls the output of log messages to standard output. See the logback PatternLayout documentation for the available conversion sequences. |
STREAMBASE_LOG_LEVEL
|
streambase.log-level | 0 | This setting controls the severity of log messages to standard output. See the table below for a mapping of integer keys to log levels. |
The following table maps STREAMBASE_LOG_LEVEL integer
settings to message levels in the Logger API.
| Level | Method | Notes |
|---|---|---|
| –2 | ERROR | |
| –1 | WARN | |
| 0 | INFO |
The default setting. Previous StreamBase releases called this
level notice.
|
| 1 | DEBUG | Level 1 has been eliminated, but the value is maintained for backwards compatibility. It is set equivalent to DEBUG. |
| 2 | DEBUG | |
| 3 | TRACE |
Previous StreamBase releases called this level debug2.
|
By default, all classes necessary to use the logging feature are available in the
standard StreamBase Java Client Library's JAR file, sbclient.jar. To use an alternative logging back end, you must:
-
Add the alternative Java Client Library's JAR file to your CLASSPATH, replacing
sbclient.jar. -
Include the JARs for your alternative logging system on the CLASSPATH.
An alternative JAR file, sbclient-no-logging-backend.jar, can be used if you want to use a
different back end for slf4j. The
sb-config command was extended to
support this use case. You would normally use a command like the following to
return the path to the StreamBase Java Client Library's JAR file for
use in adding to your CLASSPATH:
sb-config --classpath
But when using an alternative logging back end, use the following version of the command instead:
sb-config --no-logging-backend --classpath
This version generates the path to a version of the JAR that does not include the
Logback back end.
Note
When using the alternative JAR file, the configuration environment variables and Java properties described above are not available.
Now add the JAR files that support the alternative logging system to your CLASSPATH.
For example, to use log4j as your logging back end, include two JARs on the CLASSPATH when your application runs:
-
slf4j-log4j12.jar, obtained from the slj4j 1.5.0 distribution. -
The jar for log4j itself, obtained from the log4j web site.
Using JDK logging is simpler. In this case, add the single JAR file slf4j-jdk14-1.5.0.jar, to the CLASSPATH.
These alternative back end JARs must be on the CLASSPATH at runtime. It does not
matter what is on the CLASSPATH when you build against the StreamBase
client API, as long as you do not use classes from the ch.qos.logback package, only from org.sl4j.
Further documentation on slf4j is available at the slf4j web site.
Logback can be configured in more
complicated ways through an XML file in the classpath named logback.xml. For example, Logback can append to
a syslog daemon. There is an online wizard
for generating Logback configuration files.