StreamBase recognizes a set of environment variables that affect the behavior of StreamBase Server; some variables affect StreamBase Studio. You can define StreamBase environment variables using any of the methods native to your system. Environment variables control and take precedence over certain properties defined in StreamBase Server configuration files.
Environment variable expansion in StreamBase Server configuration files is not limited to the variables on this page. The values of all variables in the environment that starts the StreamBase Server instance can be used, as described in Using Environment Variables in Configuration Files.
The environment variables on this page affect:
-
The behavior of the next StreamBase Server instance or client you start. That is, a change in an environment variable setting does not affect a currently running server or client.
-
The behavior of clients built with the StreamBase C++ or .NET APIs. (Java clients use Java properties instead of environment variables, as described in StreamBase Java Properties.)
The environment variables are:
-
STREAMBASE_CRASH_QUIET (Windows only)
-
STREAMBASE_CRASH_TRACE (Linux only)
Notes
-
On Windows, environment variables that you explicitly set take precedence over any corresponding StreamBase keys in the Windows registry. For further information, see Running StreamBase Server as a Windows Service, in the Administration Guide.
-
The StreamBase installer does not set the
STREAMBASE_HOME
orPATH
environment variables, which allows support for installing multiple versions of StreamBase. See StreamBase Command Prompt for details.
Use this variable in conjunction with the STREAMBASE_USE_CUSTOM_LOGGING variable. When setting that variable to true, set
SB_CLIENT_CLASSPATH to the full, absolute path to sbclient.jar
or one of its alternatives (sbclient-no-logging-backend.jar
or sbclient-no-logging.jar
). See Using StreamBase Logging to understand these alternatives.
Set to 1 to emit error tuples using the pre-7.1 schema, with the orginalTuple
field emitted as a blob. Set to 2 (the default in StreamBase 7.1.0 or later) to emit error tuples using the 7.1+ schema,
with originalTuple
emitted as a JSON object string. This variable is also available as a Java system property, streambase.appgen.error-schema-version
. See Schema of the StreamBase Error Tuple for more on this subject.
When set to true
, you can use the runtime tracing features of StreamBase Server, as described in Runtime Tracing and Creating Trace Files. You can make the same setting with the -Dstreambase.codegen.trac-tuples=true
system property.
When set to yes
(the default), the StreamBase Server process can create a crash dump in the event of a segmentation fault.
When set to yes
(the default), the StreamBase Server process can create the crash dump without having to launch a dialog box. The no
setting may be appropriate in development, but should not be used in production, or when you are starting the StreamBase
Server as a service.
Available on Linux only. If the STREAMBASE_CRASH_HANDLER
value is yes
(the default),
causes the crash handler to print a stack trace.
STREAMBASE_CRASH_TRACE
=yes
Sets the directory to be used for persistent data when using disk-based Query Tables (if your license enables their use). The precedence order is:
-
If present on the
sbd
command line, the path specified in the
option.--datadir
-
The path specified with this
STREAMBASE_DATA
environment variable, if present. -
In the server configuration file, the value of the
datadir
parameter in the
section.<server>
-
On Windows only, the path specified in the Windows Registry at the following location:
HKEY_LOCAL_MACHINE\SOFTWARE\StreamBase Systems\StreamBase
.n.m
\DataDir -
If not specified, or if the special value
+TEMP+
is used, a temporary directory is created on server startup and deleted on shutdown.
For more information, see Using the Query Table Data Construct in the Authoring Guide.
Specifies the directory in which StreamBase was installed. On UNIX, set this variable before running StreamBase commands. For example:
export STREAMBASE_HOME=/opt/tibco/sb-cep/n.m
The recommended method to set StreamBase environment variables on UNIX, and an essential method if you use the tar.gz
installation method, is to use sb-config --env, as shown in this example:
eval `/opt/tibco/sb-cep/n.m
/bin/sb-config --env`
On Windows, before release 5.0, this and the PATH
environment variable were set by the StreamBase installer. Beginning in release 5.0, StreamBase does not set these variables,
because you can now install multiple versions of StreamBase on Windows. StreamBase instead provides the StreamBase Command Prompt in the Start menu. For StreamBase 5.0 and later, run StreamBase utilities and start the sbd server process from a StreamBase Command Prompt, not an ordinary Windows command prompt.
If you have a single StreamBase installation on a Windows machine, you may prefer to set STREAMBASE_HOME and PATH in the global
environment with sb-config --setenv . If you have a mixed installation of StreamBase 3.x and 6.x, do not use --setenv
, as explained in StreamBase Command Prompt.
The first command below sets the global environment for the currently logged-in Windows user. The second command does the same for all users.
"C:\TIBCO\sb-cep\n.m
\bin\sb-config" --setenv "C:\TIBCO\sb-cep\n.m
\bin\sb-config" --setsysenv
STREAMBASE_HOME
is referenced in the template sbd.sbconf
configuration file for the StreamBase Server. The following is an example of STREAMBASE_HOME
used in sbd.sbconf
:
<authentication> <param name="enabled" value="true"/> <param name="type" value="sb-password-file"/> <param name="filepath" value="${STREAMBASE_HOME}/etc/sbpasswd"/> </authentication>
Specifies an alternate path to the StreamBase license file. The default file name is streambase_license.xml
and the default location is STREAMBASE_HOME/etc, and these names do not need the environment variable. If you place the license
file in any other location, use this variable to point to the full, absolute path to the file. The license file must be in
the XML format delivered with the StreamBase installers, but does not need to have the default name if you point to another
file name with STREAMBASE_LICENSE.
Sets the level of information, warning, and debug messages emitted by StreamBase Server. For all supported platforms, the log levels are integers from -2 to 3, inclusive. See the table in Log Levels to understand the log level meanings.
Note that setting the STREAMBASE_LOG_LEVEL
variable is only useful when running sbd interactively in StreamBase Command Prompts or in UNIX terminal windows. When you run sbd in background mode with the -b
flag, it is configured by default to write messages to syslog
instead of to stdout
. See Server Background Mode and Logging for more information.
The variable is largely superseded by the -J
option, which is honored by the same set of commands listed below. For more on the -J
option, see the reference page for any of those commands.
Use STREAMBASE_JVM_ARGS
to specify one or more arguments to append to the default arguments for the JVM that will run a StreamBase command. For example,
set STREAMBASE_JVM_ARGS=-Xms1024M
to specify a minimum of one gigabyte of RAM. Remember that if you change any of the primary memory-setting JVM arguments
(-Xms
or -Xmx
), then the StreamBase Server defaults for those settings no longer apply. Thus, if you set one of these settings with this
variable, set them all.
The following commands from the base StreamBase kit check for and append the contents of this variable to their startup routines: jsbadmin, jsbc, jsbclientgen, sbargen, sbbundle, sbcipher, sbd, sbfeedsim, sbprofile, sbproxy, sbrecord, and sbtest. The following commands from external adapter kits also respond to this variable: sb-ems-* and sb-jdbc.
Because so many commands are affected by this variable, it is unwise to export this variable to the global environment, because the JVM settings for one command are not likely to be appropriate for all commands. Instead, use it for ad hoc adjustments to the JVM arguments per invocation. For the Bash shell on UNIX, use syntax like the following:
STREAMBASE_JVM_ARGS=settings
sbbundlesbbundle-args
For Windows, you can configure per-invocation usage by wrapping the command of interest in a batch script, surrounded by setlocal and endlocal commands.
Use STREAMBASE_MAX_INPUT_PACKET_SIZE
to increase the maximum size of packets used by C++ clients when communicating with StreamBase Server. If unspecified, the
default is 1 megabyte.
This environment variable controls how many milliseconds a C++ StreamBase dequeuing client will tolerate not receiving anything
from the StreamBase Server to which it is connected. The default value is 120 seconds (120000
). By default, StreamBase Servers emit client heartbeats every 10 seconds, so that StreamBase applications have no requirement
to send data regularly.
StreamBase Servers can be configured to send heartbeats faster, slower, or not at all. The quiescent timer only starts after the first heartbeat is received; so if a server never sends a heartbeat, clients will not have quiescent protection.
When designing a high availability StreamBase cluster, you can use this environment variable for clients, to set how often
the client should try to reconnect to the primary or secondary machine when the connection to the server is dropped. The value
is in milliseconds. The default is 5000 (5 seconds). This environment variable is useful with C++ clients. By contrast, Java
clients can use the streambase.reconnect-sleep
system property as described in StreamBase Java Properties.
If set to any value, StreamBase programs assign a terminal window title to match the name of the executable being run. By
default, terminal titles are not affected. On UNIX, this can be helpful if you have many terminal windows open for sbd, sbfeedsim
, sbc dequeue
, sbmonitor
, and so on.
The URI for StreamBase Server. The default is sb://localhost:10000
. You can set this environment variable if the Server is on another node or listening on another port. For example, if the
Server is running on host server.example.com
at port 20000, set the STREAMBASE_SERVER
value as sb://server.example.com:20000
. This environment variable can be read by C++ clients, adapters, and most StreamBase command-line utilities (such as sbc) to determine a non-default StreamBase Server location or port.
Specifies a list of arguments for the JVM that runs StreamBase Studio. This variable should only be necessary on rare occasions, usually under the direction of TIBCO Technical Support.
Important
Using this variable overrides and replaces the default vmargs
passed to Studio. If you use the variable for any purpose, you MUST include the default values like the following.
STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M
On 64-bit platforms with physical RAM of 4 GB or more, you can set the –Xmx
setting to a larger value, such as –Xmx1024m
or even –Xmx2048m
.
To use this environment variable correctly, set the default values, then add your setting at the end:
STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M \
-Dyour-setting
For example:
STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx768M \ -Dstreambase.tuple-charset=UTF-8
You may also want to re-specify the default GC settings as described in Garbage Collection Policy Settings
Set STREAMBASE_TCP_NODELAY to true
to disable the Nagle algorithm on network connections. In addition, for Java clients, you can set the system property streambase.tcp.nodelay
to true
. While it is best to set STREAMBASE_TCP_NODELAY on both the client and server, setting it on the server is often more important
than setting it on the client.
Note
Disabling the Nagle algorithm can improve latency characteristics, but it can also make network utilization less efficient. This may reduce the maximum throughput rates for a given network interface.
When designing a high availability StreamBase cluster, you can use this environment variable in conjunction with client dequeue heartbeats to set the timeout for dequeues. The value is in milliseconds, and the default is 120000 (120 seconds). By default, StreamBase Servers emit client heartbeats every 10 seconds, so that StreamBase applications have no requirement to send data regularly. StreamBase Servers can be configured to send heartbeats faster, slower, or not at all. The quiescent timer only starts after the first heartbeat is received. Thus, if a server never sends a heartbeat, clients will not have quiescent protection.
This environment variable is useful with C++ clients. By contrast, Java clients can use the streambase.tuple-connection-quiescent-limit
system property as described in StreamBase Java Properties.
When designing a high availability StreamBase cluster, you can use this environment variable for clients, to set a timeout value on reads and writes between the client and server. This timeout is used by the client to recognize failure of the server. Consider carefully when using this property. A timeout value that is too long may cause the client to hang for that period before it fails over to the other server. Too short of a value may cause the client to disconnect prematurely from the server if the server is busy. The value is in milliseconds, and the default is 15000 (15 seconds). A value of 0 disables the timeout (some operations will block forever). For further information, see Creating C++ Clients.
This environment variable is useful with C++ clients. By contrast, Java clients can use the streambase.tuple-connection-timeout
system property as described in StreamBase Java Properties.
Path to and name of the StreamBase Server configuration file used for conducting unit tests, which must contain the path to the directory containing your JUnit test class file (usually the java-bin folder of the Studio workspace). Can be specified or overridden using the streambase.unit-test.server-conf system property or the sbunit command.
If set to
(the default value), or if not set, StreamBase uses its internal JDK installed in true
streambase-install-dir/jre
, and ignores any setting of the JAVA_HOME
environment variable. This applies to both StreamBase Studio and StreamBase Server run independently of Studio with the sbd command.
If set to false
, Studio and sbd use the external JDK defined in the JAVA_HOME
environment variable. JAVA_HOME
must be set to the full, absolute path to the top-level directory containing your JDK.
If set to false
, but no JAVA_HOME
is defined, StreamBase searches the system PATH for a JDK. If not found, StreamBase looks in standard installation locations
for a JDK. If still not found, neither Studio nor sbd will start.
If set to
, StreamBase automatically calls true
sbclient-no-logging-backend.jar
wherever sbclient.jar
would be used. This allows you to use an alternative Java logging system as described on Using StreamBase Logging. When set to true, the JAR files that support your alternative logging system must be specified on the Server's classpath,
or in a <jar>
child element of the <java-vm>
element of the server configuration file. You can also specify the path to sbclient.jar
(and its embedded Logback logging) or to one of its alternatives with the SB_CLIENT_CLASSPATH
environment variable described above in SB_CLIENT_CLASSPATH.
Specify a timeout value in milliseconds that clients built with the StreamBase Client Library will wait for a response from StreamBase Server. This setting applies in the rare case when the server is alive and listening, but not responding.
Use this environment variable to place Java code in the classpath of StreamBase Studio, and of StreamBase Server as launched
from Studio. For example, set STUDIO_BOOT_CLASSPATH
, pointing to the full, absolute path to a database vendor's JDBC JAR file in order to use a JDBC database as the data source
for a feed simulation. See Feed Simulation with a JDBC Data Source for details.
StreamBase Server writes internally generated temporary files to a temporary directory. The location of the temporary directory used is the first valid directory path found in the following search sequence:
—Specified with the streambase.tmpdir Java system property
|
—The value of the TMP environment variable |
—Specified with the java.io.tmpdir system property (Windows only)
|
—/var/tmp on UNIX or C:\Windows\Temp on Windows
|
Because the TMP environment variable is used before java.io.tmpdir
, on Windows, make sure that any TMP environment variable you use specifies a path with no spaces in any path element. If
another program requires a TMP path with spaces, then use the streambase.tmpdir
property to override the temporary directory location for StreamBase Server.
The java.io.tmpdir
system property uses a platform-specific algorithm to identify a temporary directory. On Windows, this search calls the Windows
API GetTempPath()
, which searches the TMP, TEMP, and USERPROFILE environment variables in that order. In Windows domain login environments,
it is possible that your USERPROFILE directory is on a network share, and it is also possible that TMP or TEMP variables point
to a subdirectory of your USERPROFILE directory on a network share. In these cases, explicitly set streambase.tmpdir
or explicitly set TMP in the environment that runs StreamBase Server to avoid writing temporary files to a network location.