- Index

< Previous |  | Next >

## 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.

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 configuration elements in a HOCON file of type sbengine. See Interpreting Trace Files for more on setting up for tracing.

## 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 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`), and StreamSQL (`ssql`).

  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 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.

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 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.

  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 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`

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 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.

## 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.

## SEE ALSO

sbc
syslog(3)