Using StreamBase Logging

The StreamBase Java Client library uses SLF4J, the Simple Logging Facade for Java, for all internal logging. TIBCO 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 provides a front-end facade for various Java logging system back ends that can be loaded at deployment time. The back ends SLF4J supports include JDK 1.4 Logging, Log4J, and Logback, among other systems. StreamBase uses two logging back ends under different circumstances:

The StreamBase installation includes two samples that illustrate the settings to configure logging and to enable an alternate logging system. The samples are:

The default Logback logging back end can be configured with environment variables, Java system properties, or with a configuration file as described in Configuration for Logback Logging. If both an environment variable and system property are specified, the system property takes precedence. The settings that affect Logback logging are shown in the following table.

You can further configure Logback with a configuration file, as described in Configuration for Logback Logging below.

The following table maps STREAMBASE_LOG_LEVEL integer settings to message levels in the Logger API.

Most StreamBase adapters allow you to set a log level independently for the adapter than for the hosting StreamBase Server:

For example, adapters can set the log level to WARN or ERROR for messages emitted from the adapter while the hosting server is still set to its default INFO level. This allows you to troubleshoot adapter connectivity issues without having to wade through hundreds of verbose server messages.

Embedded adapters participate in the logging back end currently used by the hosting server. Thus, independent adapter log level settings are passed through to the SLF4J front end and Logback back end when running the server in the foreground or from Studio, and are passed to the Log4j back end when running the server in the background.

StreamBase's default settings for Logback logging are as follows:

The following sbd startup message, taken from the Console view in StreamBase Studio, illustrates the components of the default log message pattern. (The message is shown on two lines for publication clarity.)

2011-02-22 13:30:13.721-0500 [ThreadPool-1] INFO  c.s.sb.sbd.net.StreamBaseHTTPServer - 
   sbd at Argyll:10000; pid=4048; version=7.0.4; Listening

The components of the default log message pattern have the meanings shown in the following table.

Consult the Logback documentation for PatternLayout for the available log message pattern components.

You can configure Logback logging in simple ways without resorting to a configuration file. You can:

For more complex Logback configuration, specify a Logback configuration file, which is often an XML file named logback.xml. There is an online wizard for generating Logback configuration files that makes basic logging setup straightforward that you can access at http://wizard4j.org/pc?action=languageExamples. Use the wizard to generate a Logback XML configuration file to change the log destination, configure filename rolling rules, specify log filename patterns and log string patterns, and so on. You can also download a logback.xml template file to modify.

If you inadvertently specify both STREAMBASE_LOG_PATTERN and a Logback configuration file, any message pattern specified in the configuration file is the one used by StreamBase Server.

The StreamBase sample logging-logback includes an example logback.xml configuration file that illustrates a setup for both a console appender and a rolling file appender.

StreamBase incorporates Logback version 1.1.2. Documentation on the Logback website may describe configuration elements added in later versions of Logback. To obtain accurate documentation on the Logback version included with StreamBase, follow these steps to obtain version-specific Logback documentation:

StreamBase supports configuring Logback using any of the configuration rules and methods documented for Logback 1.1.2.

It is common in development environments to have Logback locate its configuration file on the Java runtime classpath. When developing with StreamBase Studio, you can place your logback.xml file in the java-src directory of your Studio project. This makes the file a Java resource on the Java Build Path when running your application from Studio and when deploying your application with a StreamBase bundle file generated from your Studio project. To specify using java-src/logback.xml when running sbd from the command line, make sure your server configuration file includes elements like the following example:

<streambase-configuration>
...
  <java-vm>
    <dir path="java-src"/>
  </java-vm>
...
</streambase-configuration>

Another way to configure Logback is to specify the path and name of the Logback configuration file using the logback.configurationFile Java system property. Using this property allows you to separate the Logback configuration file's location from your development environment, which allows you to locate the file independently in the development and deployment environments using an environment variable or other method. This allows you to use separate Logback configuration files for different situations.

Specify this system property in the server configuration file with the <sysproperty> child element of the <java-vm> element:

<streambase-configuration>
...
  <java-vm>
    <sysproperty name="logback.configurationFile" 
                 value="/path/to/logback.xml"/> 
  </java-vm>
...
</streambase-configuration>

A Logback configuration file whose location is specified with <sysproperty> is considered a third-party resource file, and is not automatically included in StreamBase bundles. To make sure your logback.xml file is included in your bundles, add the file using the Bundling project properties page, or use the sbbundle --include command.

In the StreamBase Java Client library, the base class, Operator, for Java operators and embedded adapters provides the convenience method getLogger(). This returns an org.slf4j.Logger object that should thereafter be used for logging messages and exceptions in your code. The logError() method from previous StreamBase releases and all related convenience methods have been deprecated. TIBCO recommends replacing any 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().

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 pop-ups 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 one or more logs. 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 further information.

The SLF4J logging mechanism captures most, but not all debug and console messages from the running server. There are two sources of logging messages emitted from StreamBase Server:

If your site has standardized on a different Java logging mechanism, you can configure StreamBase to use a different logging system. You can:

StreamBase provides three versions of the Java Client API JAR file. This JAR file is used by StreamBase Server and by all custom client, operator, and adapter code. The three client JAR file versions are:

In general, to use an alternative logging back end, you must:

As described in Logging Overview, the Log4J back end is automatically used when StreamBase Server is run with sbd -b on the command line, or when run as a Windows service (which requires the use of sbd -b). This section describes the configuration steps that allow you to use Log4J for all StreamBase logging, including when running from Studio or running in the foreground with the sbd command.

There are four criteria that must be met to successfully replace the Logback back end with the Log4J back end. The criteria can each be implemented in different ways to impact the different ways to run StreamBase applications.

The alternative JAR files must be on the classpath at runtime. It does not matter what is on the classpath when you build against the StreamBase Client library, as long as you do not use classes from the ch.qos.logback package in your custom code, only classes from org.slf4j.

Further documentation on SLF4J is available at the SLF4J web site.

The StreamBase sample logging-log4j implements examples of all the above implementation methods for all four criteria, and runs equally well in Studio or at the Unix or Windows command prompt with sbd -f sbd.sbconf. The sample can be bundled and the resulting bundle can be run as an argument to the sbd command.

export CLASSPATH=`sb-config --classpath`:$CLASSPATH

export CLASSPATH=`sb-config --no-logging-backend --classpath`:$CLASSPATH

To replace the Logback back end with JDK 1.4 logging, use the same criteria and implementation steps as described in the previous section for Log4J.

Note that there are two exceptions to that implementation:

If your site has standardized on a different version of SLF4J that conflicts with the version bundled in both sbclient.jar and sbclient-no-logging-backend.jar, follow these steps:

Back to Top ^