StreamBase recognizes a set of environment variables that can affect the behavior of EventFlow and LiveView fragments. You can define StreamBase environment variables using any of the methods native to your system.
Note
Remember that your StreamBase Application runs in the context of one or more StreamBase Runtime nodes that may be run on multiple hosts in an HA deployment. It is also possible that these nodes are encapsulated in a Docker container. For these reasons, do not rely on environment variables being available or even settable under all runtime conditions.
By default, fragment launches in StreamBase Studio inherit and include the system environment variables set in the shell from which Studio was started. You can specify individual environment variables using the Environment tab of the Run Configuration for a fragment. You can also optionally configure any single fragment launch, or all launches, to ignore the system environment in the next run.
Environment settings are honored when a node is installed. Remember that Studio re-uses installed nodes for subsequent launches of the same fragment. Therefore to change environment variable settings while developing a fragment, you must stop and remove its runtime node using buttons in the Clusters view, then re-launch the fragment. This installs a new node with the new settings.
Environment variable settings can be inherited from the system environment during a fragment launch in Studio, or can be explicitly specified in a Studio run configuration, or both. In all cases, no environment settings are preserved in any generated fragment archive. Likewise, no environment settings are carried into any StreamBase Application archive that contains a fragment archive.
The epadmin command also inherits the system environment at node installation time. This gives administrators maximum flexibility to change settings for the different environment of deployment hosts.
In general, instead of relying on environment variables, It is a best practice to use substitution variables in configuration files, possibly in conjunction with module parameters.
The environment variables are:
-
STREAMBASE_CRASH_QUIET (Windows only)
-
STREAMBASE_CRASH_TRACE (Linux only)
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 Interpreting Trace Files. You
can make the same setting with the streambase.codegen.trac-tuples=true system property specified in a
configuration file of type c.t.e.streambase.c.sbengine, with the root object
StreamBaseEngine.
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), STREAMBASE_CRASH_TRACE=yes
Specifies the directory in which StreamBase is installed. On UNIX, set this variable before running StreamBase commands. For example:
export STREAMBASE_HOME=/opt/tibco/str/11.1
The recommended method to set StreamBase environment variables on UNIX, and an
essential method if you use the archive-bin
installation method, is to use sb-config
--env, as shown in this example:
eval `/opt/tibco/str/11.1/bin/sb-config --env`
On Windows, the StreamBase installers do not set the PATH and StreamBase-related environment variables, because you can install multiple versions of StreamBase on Windows. StreamBase instead provides the StreamBase Command Prompt in the Start menu. Run StreamBase utilities from a StreamBase Command Prompt instead of from 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 . However, if
you have a mixed installation of StreamBase releases, such as StreamBase 7.x and
10.x, do not use --setenv. This is explained further 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\str\11.1\bin\sb-config" --setenv "C:\TIBCO\str\11.1\bin\sb-config" --setsysenv
This variable is deprecated, as is the related system property streambase.log-level. Instead, migrate to standard Logback
configuration mechanisms described in Using StreamBase Logging.
This variable is deprecated, as is the related system property streambase.log-pattern. Instead, migrate to standard Logback
configuration mechanisms described in Using StreamBase Logging.
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 and -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, sbcipher, 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 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, 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 the support team.
Important
Using this variable overrides and replaces the default vmargs passed to Studio. If you use the variable for any purpose
other than setting -Xms or
-Xmx, you MUST re-specify
-Xms and -Xmx if you are using non-default values.
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
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.
Specify one of the following values:
-
fallback — If set to
fallback, or not set, this configures Studio to try to locate a system-installed JDK, and to use the Streaming bundled JDK only if an acceptable system JDK is not found. -
true — Always use the JDK bundled with Streaming. This was the default value of STREAMBASE_USE_INTERNAL_JDK before release 10.4.0.
-
false — Use the JDK specified in the
JAVA_HOMEenvironment variable, if set.JAVA_HOMEmust be set to the full, absolute path to the top-level directory containing your JDK.If set to
false, but noJAVA_HOMEis defined, Streaming searches the system PATH for a JDK. If not found, Streaming looks in standard installation locations for a JDK. If still not found, Studio does not start.
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.