Server Background Mode and Logging

This topic describes running StreamBase Server in background mode, describes how to configure the Apache Log4j logging mechanism enabled in that mode, and describes how to configure syslog on UNIX to receive messages from Log4j.

Background Mode Overview

Run StreamBase Server in background mode by specifying the –b option on the sbd command line, or by running StreamBase Server as a Windows service. (TIBCO does not recommend running sbd -b at the StreamBase Command Prompt on Windows.)

In background mode, debug and console messages normally written to standard output using the embedded Logback mechanism are automatically redirected by default to an alternative embedded Apache Log4j logging mechanism. The reason for this automatic redirection is that Log4j provides a logging appender that can write to the Windows Event Log.

StreamBase logging in general is discussed in Using StreamBase Logging.

Specifying a Working Directory

Use the -w or --working-directory options with the sbd command to specify a working directory for StreamBase Server when run in the background. The path specified with -w is not automatically on the module search path, which must be specified as usual.

When specifying a startup working directory, you can express paths to resource files relative to the root of the working directory, or you can specify full, absolute paths.

Specifying a Working Directory for Bundle Files

When using the -w or --working-directory options in conjunction with running a bundle file, the working directory you specify is where the bundle file is unzipped before running its contents.

If you specify an empty directory with -w, it is treated as a temporary directory, and is automatically and silently deleted when sbd exits. The same behavior occurs when you run a bundle file without using -w, in which case an automatically determined temporary directory is created to hold the bundle contents and is deleted on sbd exit.

If you use -w, but specify a path to a directory with any existing contents, that directory is preserved on sbd exit. You can use the streambase.sbd.delete-working-bundle-dir system property to modify this delete-on-exit behavior. Set -Dstreambase.sbd.delete-working-bundle-dir=true to delete the working directory's contents even if you specify a non-empty path with -w. You can use the sbd command's -J option to specify the system property on the sbd command line.

Specifying Paths When Using the Default Working Directory

When StreamBase Server starts in background mode without using the -w or --working-directory switch, its default working directory is the root of the file system, / on UNIX or %windir%\System32 on Windows. When using the default working directory, you must express the path to any file system resources used by the server with full, absolute paths. Use full paths on the sbd command line and in the server configuration file.

Note

When using sbd -b on the command line, the launch of sbd fails if you specify a file system resource with a relative path. For example, the following commands work normally with relative paths because -b is not used:

UNIX:    sbd -f ./sbd.sbconf ./myapp.sbapp
Windows: sbd -f sbd.sbconf myapp.sbapp

However, if you add -b to these commands, sbd fails to start, reporting the failure to the Event Log for Windows or to syslog for UNIX. To avoid this error, use full, absolute paths, as shown in the following examples:

UNIX:    sbd -b -f /home/sbuser/sbproj/sbd.sbconf /home/sbuser/sbproj/myapp.sbapp &
Windows: sbd -b -f c:\sbproj\sbd.sbconf c:\sbproj\myapp.sbapp

Some of the file system resources that might be used by the server are described in the following table.

File System Resource Specifying with Server in Background Mode
server configuration file Specify an absolute path to the configuration file with the -f option on the sbd command line.
primary application file or bundle file to run Specify an absolute path to the file, either as an argument on the sbd command line, or in a file attribute of an <application> element in the server configuration file. You can also create a StreamBase bundle for your application and specify the full path to the bundle file.
custom function plug-ins Specify an absolute path to a file with the file attribute, or an absolute path to a directory with the directory attribute, when using the <plugin>, <module-search>, or <operator-resource-search> elements in the <global> section of the server configuration file.
Java resources Specify absolute paths to a Java home directory, and to any JAR files or other resources required by custom Java-based adapters and operators. For example, in the <java-vm> element of the server configuration file, specify absolute paths in:
  • The value attribute of the java-home name-value attribute pair of the <param> element.

  • The file attribute of the <jar> element.

  • The path attribute of the <dir> or <library> elements.

  • The value attribute of any name-value pairs that specify a path, when using the <sysproperty> element.

data directory for disk-based Query Tables Specify an absolute path to a directory, whether specified with --datadir on the sbd command line, or in the STREAMBASE_DATA environment variable, or with the datadir attribute of the <server> element in the server configuration file.
Authentication password database Specify an absolute path to the sbpasswd file when using the filepath-value attributes of the <param> child element of the <authentication> element.

Background Mode On UNIX

On supported UNIX platforms, StreamBase Log4j logging is configured by default to write to the UNIX syslog mechanism using the standard UDP port for syslog remote access. Syslog must be configured to listen on its standard port, as described in Syslog Configuration on UNIX.

Run the server in background mode with a command like the following example:

sbd -b -f /path/to/config/sbd.sbconf &

In the specified server configuration file, identify the absolute path to the primary application file to run, plus any container information, TCP port to listen on, modules to load, and so on. You can set up a server to run automatically on host reboot by using with a script managed by cron, or using the init.d mechanism installed by the StreamBase RPM installer (described in Installing StreamBase on Linux), or using another method you devise.

Background Mode on Windows

On Windows, TIBCO discourages using sbd –b at the StreamBase Command Prompt except for short-term testing. Instead, the –b option is designed to be used when specifying the command line for running StreamBase Server as a Windows service, as described in Running StreamBase Server as a Windows Service.

When running in the context of a Windows service, StreamBase Server's Log4j logging is configured by default to write to the Windows Event Log. You can configure other logging options as described in the next section.

Note

If you run sbd –b at the StreamBase Command Prompt, the Server emits several benign console warning messages that complain about multiple SLF4J bindings. This is because the StreamBase Command Prompt specifies a classpath that includes the default sbclient.jar, in which the SLF4J front end is configured to log to the Logback back end. But the sbd command itself, when used with -b, also internally references the SLF4J front end, this time configured to log to the Log4j back end.

Even though discouraged, it is still possible to run sbd –b at the StreamBase Command Prompt without warning messages by unsetting the CLASSPATH environment variable and following the other steps in Advanced: Replacing Logback with Log4J. For an example, see the batch file run-sbd-with-env.cmd in the logging-log4j sample.

Log4j Configuration

Configure background mode's Log4j logging mechanism by editing its configuration file. For both UNIX and Windows platforms, the StreamBase Log4j configuration file is installed by default in STREAMBASE_HOME/etc/log4j.configuration.

Your Log4j configuration can redirect the output to a file or can take advantage of any other valid Log4j mechanism. Refer to standard Log4j documentation for the various configuration options.

You can change the location or name of the Log4j configuration file by setting the log4j.configuration system property for the JVM running the server. Do this in the server configuration file, using either the <jvm-args> or <sysproperty> elements, like these examples:

<param name="jvm-args" value="-Xms128m -Xmx512m 
   -Dlog4j.configuration="file:/c/sbproj/mylog4j.configuration" />

or

<sysproperty name="log4j.configuration" 
    value="file:/home/sbuser/sbproj/mylog4j.configuration" />

Notice that the system property value is a Java URI, not a simple path name. See StreamBase Server Configuration File XML Reference for more on server configuration file elements.

Two Sources of Logging Messages

Background mode's Log4j logging mechanism captures most, but not all debug and console messages from the running server. There are two sources of logging messages from StreamBase Server:

  1. When running in background mode, the SLF4J back-end logging mechanism and the Log4j front end capture everything that runs in the server's Java virtual machine (JVM), including output from all running StreamBase applications, as well as much of the server infrastructure. The output from these components will conform to the configuration in the log4j.configuration file.

  2. StreamBase Server uses a small amount of native code for each platform to start and manage the JVM. Messages from this startup code includes information about server startup and shutdown, plus some miscellaneous output. These messages are not directed through SLF4J and Log4j, but are delivered directly to syslog for UNIX and to the Event Log for Windows.

On UNIX, you must configure the syslog daemon to listen for these startup messages, as described in the next section.

Syslog Configuration on UNIX

The syslog daemon receives messages in two ways, from programs making a system call that writes directly to syslog, or from programs that send messages to a known, standard UDP port. Messages sent from StreamBase Server's native startup code use the system call method, and do not require special configuration. However, messages sent from Log4j to syslog use the UDP port method, which must be enabled.

On Linux platforms, syslogd is typically installed but not configured to listen by default on its UDP port. Be aware that syslog logging is advisory only, and does not provide notification of dropped messages, which could happen when syslogd is not set up to listen for remote messages.

On Linux, the method to configure syslogd for remote access varies by Linux distribution. The following shows the steps for the Linux platforms supported by StreamBase.

  • For Red Hat Enterprise Linux version 6 and above, first, add (or uncomment) the following lines to /etc/rsyslog.conf:

    $ModLoad imudp.so
    $UDPServerRun 514
    

    Then, restart the rsyslog service:

    /sbin/service rsyslog restart
    
  • For Red Hat Enterprise Linux versions 5 and earlier, add -r to SYSLOGD_OPTIONS in /etc/sysconfig/syslog. Then stop and restart the syslog daemon by running the following command as root: /etc/init.d/syslog restart.

  • For SUSE Linux Enterprise Server, uncomment the UDP line in /etc/syslog-ng/syslog-ng.conf.in. Then run the following commands as root:

    /sbin/SuSEconfig --module syslog-nt
    /sbin/rcsyslog restart
    

On Solaris 10, remote access to syslogd may already be configured by default. If you need to enable it, use steps like the following, run as root:

svccfg -s system/system-log setprop config/log_from_remote = true
svcadm refresh svc:/system/system-log

See the syslogd(8) documentation for details. Updates and service packs applied to Solaris and Linux may change the example commands shown here, so be sure to check the latest documentation for your Solaris or Linux installation.

Back to top