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 Managing Error Tuple Schema Upgrades 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 allows 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
, -Xmx
,
-XX:MaxPermSize
, and for 64-bit servers, -XX:+UseCompressedOops
), 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.
To use StreamBase 3.7 clients with StreamBase Server and the proxy server from release 6.3 or later, you must set the environment variable STREAMBASE_PACKING_PERCENT to zero on the hosts (and user environments) running both the proxy server and the client.
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 StreamBase Systems 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 -XX:MaxPermSize=256M
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 -Xmx512M -XX:MaxPermSize=256M \
-Dyour-setting
For example:
STREAMBASE_STUDIO_VMARGS=-Xms256M -Xmx512M -XX:MaxPermSize=256M \ -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.