sbadmin

StreamBase Administration Client — starts the StreamBase Administration Client

SYNOPSIS

sbadmin [OPTIONS] [COMMAND]

DESCRIPTION

The sbadmin command starts the StreamBase Administration Client, which lets you perform StreamBase administration tasks such as addContainer, suspend, resume, and shutdown.

You can optionally limit the use of sbadmin commands to certain designated user accounts by enabling a feature of StreamBase authentication. See the sbuseradmin reference page for more information.

Use the sbc command rather than sbadmin for non-administrative commands.

Suspending and Resuming

You can use sbadmin suspend to request suspension of an application, a container, an adapter, a Java operator, or an embedded adapter. However, not all StreamBase objects respond to a suspend request. If the specified target cannot be suspended, the command succeeds silently, but the specified target continues to run.

In general, embedded adapters supplied by StreamBase respond to suspend requests, while global operators and adapters supplied by StreamBase are not subject to suspension. The suspend and resume commands are best used with custom operators and adapters you write to extend StreamBase functionality, and for which you define suspend state behavior.

The container suspend state is a flag to which custom operators and adapters may respond, depending on how they are coded. Streams ignore the suspend state and instead respond to enqueue and dequeue STREAMSTATUS as set by sbadmin modifyContainer --enqueue= and --dequeue= commands, described below. Suspending a container applies the suspend state to all operators and adapters, but if there are none in the container that have a specific suspend state defined, then the application behavior does not change when receiving a suspend command.

Shutting Down and Restarting Containers

The sbadmin shutdown containername and sbadmain removeContainer containername commands are equivalent and you can use either one. Shutting down a container stops the execution of all operators in the container as soon as the current tuple and any pending JDBC operations complete processing. The current tuple only needs to enter an output queue to be considered complete. The shutdown process then unloads all operators, queues, and connections from memory. Once shut down, a container is no longer present in the server and cannot be restarted or reloaded with an application module. You can, however, add a new container with the same name.

Using the restartContainer command, you can restart a container without recompiling or reloading its code. Doing so eliminates any in-memory state and re-initializes connections. As restartContainer is more efficient than removing the container and re-adding it, this command is useful for testing. It can also prime the JIT compiler state for the application, because the same bytecode is executed post-restart.

If you are shutting down a container with a container connection (for example, if the output stream of one container is the input stream of another container), remove or shut down the containers using the reverse order in which they were added to the server.

Container Connections

You can set up connections between containers when you add a container with the addContainer command or when you modify existing containers with the modifyContainer addConnection command. Container connections can be one of the following types:

Stream-to-stream connections, where an output stream in one container connects to an input stream in another container. These can be asynchronous (default) or synchronous connections.
 
JMS-mediated connections, where an output stream in one container connects to a Java Messaging Service server, then an input stream in another container connects to the same JMS server. This is a stream-to-stream connection that passes through a JMS server to insure reliable delivery of messages.
 
CSV file connections, where an input or output stream in a container is connected to a URI specifying the path to a CSV file.

The syntax for expressing all forms of container connections is always destination=source, like an assignment statement in some programming languages.

See Container Connections in the Administration Guide for more on container connections.

Runtime Tracing

When enabled, runtime tracing writes tuple trace information to StreamBase Server's console or to a trace file, one per container. The default trace information is a single timestamped line per tuple. Each tuple is shown as received at each operator and stream in the application. Trace files can grow quite large very quickly, so runtime tracing is best used only for short bursts, for debugging only, to follow the progress of a single tuple or group of related tuples through an application.

You can limit the traced operators and streams by using a regular expression to name the components of interest.

You must set up for runtime tracing by specifying a system property or environment variable. Once set, you enable and disable tracing using subcommands of sbadmin addContainer or sbadmin modifyContainer, or using the <trace> element in a Server configuration file or deployment file. See Runtime Tracing and Creating Trace Files for details on setting up for tracing, and using the runtime tracing configuration options.

OPTIONS

-h [subcommand], --help [subcommand]

Displays usage text for the sbadmin command, then exits. If given a subcommand name as an argument, displays help for the specified subcommand, then exits. The subcommand argument can also precede the -h or --help:

sbadmin -h dequeue
sbadmin deq --help
-o filename

Redirects all non-error output to the specified file.

-p TCP-port

Specifies the port number on localhost for the StreamBase Server to communicate with. This is a shortcut alternative to specifying the full URI with -u in cases where the server is running on localhost but on a port other than the default 10000. Thus, the following lines are equivalent:

sbadmin -u sb://localhost:9900 listConnections
sbadmin -p 9900 listConnections

Note

The -p option is not supported for applications that have StreamBase authentication enabled (because there is no way to specify a username and password), or in conjunction with the multiple URI syntax.

-u uri

Specifies the URI of the StreamBase Server to communicate with. See the sburi page of the Reference Guide (or see sburi(5) at the UNIX shell prompt) for a discussion of the URI format and its shortcuts. The URI can also be set using the STREAMBASE_SERVER environment variable.

-w waitMS:retryMS

Specifies a wait time waitMS in milliseconds for the command to continually attempt to connect to StreamBase Server, with an optional retry period retryMS, also in milliseconds. The default retryMS is 250 milliseconds. Use this command to start sbc enqueue and dequeue commands before starting StreamBase Server. The sbc command waits and connects when the is server is ready.

--version

Prints version information and exits.

COMMANDS

addContainer containerName { file.sbapp | file.ssql | file.sbar } [ connection-expression1 connection-expression2 ... ] [--enqueue=STREAMSTATUS] [--dequeue=STREAMSTATUS] [--suspend] [--moduleSearch=path] [--resourceSearch=path] [--datadir=path][--traceStreamPattern=pattern] [--traceFileBase=basefilename] [--traceOverwrite] [--traceCompress] [--traceBuffered=true|false] [--parameter=param=value ] [--verbose]

Adds a container to the running sbd server process, assigns the new container a name, and specifies an application file to run in the context of the new container. The application file formats accepted are EventFlow (extension sbapp), StreamSQL (ssql), and precompiled archive (sbar). For more on precompiled StreamBase application files, see sbargen and Precompiled Application Archives.

When adding containers, you can optionally specify a connection between a stream in the container you are adding to a stream in an existing container, as described in Container Connections. For each connection-expression, use the syntax destination=source, and include the container name, stream name, and any intervening module names in the container. For example: containerA.instream1=containerB.module1.outstream1

You can optionally enable or disable enqueuing to or dequeuing from the container on startup. This changes the enqueue or dequeue status for embedded adapters and for enqueue and dequeue clients. The valid STREAMSTATUS values are:

ENABLED. This is the default.
DISABLED. The enqueue or dequeue will actively refuse any enqueue or dequeue requests, and throw an exception.
DROP_TUPLES. The enqueue or dequeue will silently drop tuples.

When you interrupt queuing for an application running in a container, you also interrupt queuing for any external clients, input adapters, and output adapters that were communicating with that application. See Enabling and Disabling Enqueue or Dequeue for details.

Use --suspend to specify that the application in this container should start up suspended. You can start a suspended container with the sbadmin resume command.

Use --moduleSearch to specify an absolute or relative path to a directory containing StreamBase application files that are called by this container's application as modules.

Similarly, use --resourceSearch to designate a comma-separated list of directories in which the module in the added container can search for file resources.

Use --datadir to specify an absolute or relative path to a directory to be used by this container to hold the files that implement disk query tables for the application in this container.

Relative paths for --datadir and --moduleSearch are relative to the runtime location of the sbd server, which is likely to be different between development and deployment environments. For maximum clarity, specify full absolute paths.

Use the --trace* options to manage runtime tracing, as described in Runtime Tracing.

Use --parameter to specify module parameters for the container you are adding. See Using Module Parameters for details.

With the --verbose flag, the addContainer command reports success instead of silently returning.

addDeploy file.sbdeploy | file.sbar [--verbose]

Adds the module and container specified in a deployment file (or an archived deployment file) to the running server. The deployment file must specify an application to run and container to run in, and can optionally specify container connections, trace configuration, and module parameters. In general, all the options you can specify with addContainer can also be declared in a deployment file. With the --verbose flag, the addDeploy command reports success instead of silently returning.

getLeadershipStatus

Returns one of the strings LEADER or NON_LEADER to describe the leadership status of the specified StreamBase Server instance.

getOperatorProperty operatorName [propertyName]

Displays a property or all properties for the named Java operator or embedded adapter. Optionally you can request information about a specific property; otherwise, StreamBase displays all properties for the Java operator or embedded adapter.

If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with the appropriate container name. For example:

sbadmin getOperatorProperty containerB.MyJavaOperator

killAllConnections

Disconnects all connections from the sbd server.

killConnection connectionID

Disconnects the specified connection. Obtain the connectionID string from the first field returned by an sbadmin listConnections command.

listConnections [listConnectionOption]

Lists all active client connections to the running StreamBase Server (sbd).

The listConnections command supports the following options:

--current  Shows active client connections currently conveying tuples.
--old  Shows clients still running but disconnected from the server.
--all  Shows both current and old client connections.
--clearOld  Removes client connections that are running but disconnected from the server.

For each connection, the display shows:

id

The global connection ID assigned by the server to each connection. (Use this ID with the killConnection command and the getClientIP() expression language function.)

peer, local

Client and server host name or IP address and port numbers.

memory

The size of the enqueue and dequeue buffers.

subscriptions

The names of subscribed streams, if any.

dequeued, enqueued

The total number of tuples that have been dequeued and enqueued over the life the connection.

dequeuePackets, enqueuePackets

The total number of packets that have been dequeued and enqueued over the life the connection. Tuples are not sent one at a time over the network but, by default, are batched into network packets. These settings give you an idea of how many tuples per packet are enqueued or received. It is a measure of the efficiency of the network protocol at a given time and is useful to aid understanding performance when testing across the network. Low numbers mean more network overhead per tuple. High numbers mean less.

protocolFamily

The network protocol version of the connected StreamBase Server, which increments in some but not all major releases. StreamBase client programs such as sbc and sbadmin from an older StreamBase release can always connect to servers from newer releases because of the version proxying built into StreamBase Server. However, client programs from a newer release can connect to older server releases only when they have the same protocol version.

status

Displays OK/OK if server and client are operating normally.

manageJdbcConnections close|count [datasource-name]

Lists the number of currently active JDBC connections and allows you to close a JDBC connection without having to shut down the enclosing server or container. With either subcommand, close or count, this command returns the current number of JDBC connections. Specify the case-sensitive exact name of a data source as defined in a <data-source> element of the current server's configuration file. If you do not specify a datasource-name argument, the close subcommand closes the active JDBC connection.

modifyContainer container-name [[addConnection | removeConnection] connection-expression1 connection-expression2 ...] [--where "filter-expression"] [--enqueue=STREAMSTATUS] [--dequeue=STREAMSTATUS] [trace true|false] [--traceStreamPattern=pattern] [--traceStreamPattern=pattern] [--traceFileBase=basefilename] [--traceOverwrite] [--traceCompress] [--traceBuffered=true|false] [--verbose]

Adds or removes a container connection to a running container and/or changes the enqueue or dequeue status of a container. The container connection syntax for the addConnection subcommand and each connection-expression is the same as for the addContainer command described above. The valid values for STREAMSTATUS are the same as for the addContainer command.

Use the --where option to specify a quoted predicate expression that limits the tuples sent over that connection. The predicate expression must resolve to true or false, and should match against one or more fields in the schema of the connection's stream. Since you can make more than one container connection to the same stream, you can connect to one stream multiple times, with a different filter predicate for each.

Use the trace subcommand to enable or disable runtime tracing, as described in Runtime Tracing; the trace subcommand requires an argument of either true or false. Use the --trace* options to modify the collection of trace information as described on the same page. The --trace* options have no effect unless trace is enabled. Example:

sbadmin modifyContainer default trace true --traceFileBase="tr_" \ --traceStreamPattern="Bids" --traceOverwrite --traceCompress

removeContainer containerName [--verbose]

Removes the specified container from the running sbd server process, and unloads the container's module from memory. This command is equivalent to shutdown containername, described below. With the --verbose flag, the removeContainer command reports success instead of silently returning.

restart [ operatorName1 [ operatorName2 ... ] ]

Restarts one or more Java operators or embedded adapters in a server process that were previously stopped with the shutdown command. You can separate multiple entities with a space.

If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin restart containerB.MyJavaOperator

restartContainer container-name

The container-name argument is not optional. Shuts down the specified container and restarts a new instance of the same logic without reloading the container into memory, re-establishing container connections. Network connected clients will be disconnected.

resume [ containerName | operatorName1 [ operatorName2 ... ] ]

Resumes a suspended StreamBase application, container, Java operator, or embedded adapter. You can separate multiple entities with a space.

If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin resume containerB.MyJavaOperator

setLeadershipStatus NON_LEADER | LEADER

Changes the leadership status of the specified StreamBase Server as a member of a high availability cluster, using one of the explict, case-senstive keywords LEADER or NON_LEADER. The default status is LEADER on server startup. Changes in leadership status are announced on the system.control stream of the server instance.

setOperatorProperty operatorName propertyName value

Sets a property value for the specified Java operator or embedded adapter. Use sbadmin getOperatorProperty to see the list of properties for a Java operator or an embedded adapter. If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name.

shutdown [ containerName | operatorName1 [ operatorName2 ... ] ]

Shuts down one or more StreamBase applications, containers, Java operators, or embedded adapters. You can separate multiple entities with a space.

If you are shutting down a container with a container connection (for example, if the output stream of one container is the input stream of another container), remove or shut down the containers using the reverse order in which they were added to the server.

The commands shutdown containername and removeContainer containername are equivalent. Both leave the server with no container by the specified name, and the container's module unloaded from memory. Instead of removing and then re-adding a container, you can use the restartContainer command to restart it without recompiling or reloading the code, eliminating any in-memory state and re-initializing connections.

If the server is running multiple containers with the same module, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin shutdown containerB.MyJavaOperator

status

Displays the sbd server ID, process ID, version, and client ID.

suspend [ containerName | operatorName1 [ operatorName2 ... ] ]

Suspends a running StreamBase application, container, Java operator, or embedded adapter. You can separate multiple entities with a space. If the server is running multiple containers and you need to prevent a naming conflict, qualify the Java operator or embedded adapter with its container name. For example:

sbadmin suspend containerB.MyJavaOperator

The specified target silently accepts the suspend command, but not all StreamBase objects can be suspended, as described above in Suspending and Resuming.

[sbc commands]

For convenience, the sbadmin command also accepts all the sbc commands, as listed in the sbc reference page, including status, list, enqueue, dequeue, describe, and typecheck. In a deployment that uses the StreamBase user administration system to restrict access to the sbadmin command, this feature allows authorized administrators to run the sbc commands with administrative rights.

Note

When invoking one of the sbc command's subcommands, the sbadmin -u option accepts a comma-separated list of URIs, where each URI specifies a different StreamBase Server in a high availability cluster. See the sburi page in the Reference Guide for details.

FILES

There is no configuration file for sbadmin. Enabling or changing the StreamBase authentication setting for sbadmin commands is done by editing the sbd.sbconf configuration file, which contains an <authentication> section.

ENVIRONMENT

STREAMBASE_SERVER

Optional. Contains the URI for a StreamBase Server instance. Use this variable to set a default StreamBase URI for StreamBase commands that take the -u option. If set, commands use the URI in this variable, overriding their built-in default URI, which is sb://localhost:10000. If this variable is set, you must use the -u option to communicate with any server other than the one specified in this variable. See the sburi page in the Reference Guide for more on StreamBase URIs.

STREAMBASE_LOG_LEVEL

Optional. Sets the minimum severity of messages that StreamBase writes to logging output. Default is 0, which gets NOTICE level messages and higher. Reasonable values are -1 (which disables NOTICE messages and shows only WARN, ERROR and FATAL messages), 1 (which adds INFO messages to the standard messages), and 2 (which adds DEBUG messages).

SEE ALSO

sbc
sbd(1)
syslog(3)