Apama 10.15.0 | Building and Using Apama Dashboards | Dashboard Deployment | Managing the dashboard data server and display server | Command-line options for the data server and display server
 
Command-line options for the data server and display server
The executable for the data server is dashboard_server and the executable for the display server is display_server. They can be found in the bin directory of the Apama installation.
Synopsis
To start the data server, run the following command:
dashboard_server [ options ]
To start the display server, run the following command:
display_server [ options ]
When you run these commands with the -h option, the usage message for the corresponding command is shown.
Start the display server from the dashboards directory of your Apama work directory. To do so, proceed as follows:
1. Open an Apama Command Prompt as described in Setting up the environment using the Apama Command Prompt.
2. Change to the %APAMA_WORK%\dashboards directory.
3. Invoke the executable from the command line.
You can also start display server with the --dashboardDir folder option to specify a folder for your deployed dashboards. When --dashboard folder is used, display server will be looking for the deployed dashboards from the specified folder.
Description
The dashboard_server and display_server executables can be run without arguments, in which case they start a server on port 3278 (for a data server) or 3279 (for a display server) on the local host. Note that these are the default ports used by the Deployment Configuration Editor; see Using the Deployment Configuration editor. You can specify a different port with the -d or --dataPort option.
The -c or --correlator option allows you to specify the deployment host and port for a given correlator logical name. See Changing correlator definitions for deployment.
You can enable logging with the -f and -v (or --logfile and --loglevel) options or with the log4j properties file.
Options
Both the dashboard_server and display_server executables take the following options:
Option
Description
-A | --sendAllData
Dashboard data server only. Send all data over the socket regardless of whether or not it has been updated.
-a bool | --authUsers bool
Specifies whether to enable user authentication. bool is one of true and false. By default, authentication is enabled. Set --authUsers to false for web deployments for which authentication is performed by the web layer.
-c logical-name:host:port:raw-channel | --correlator logical-name:host:port:raw-channel
Sets the correlator host and port for a specified logical correlator name. raw-channel is one of true and false, and specifies whether to use the raw channel for communication. This overrides the host, port, and raw-channel setting specified by the Dashboard Builder for the given correlator logical name; see Changing correlator definitions for deployment. This option can occur multiple times in a single command. For example:
-c default:localhost:15903:false
–c work1:somehost:19999:false
These options set the host and port for the logical names default and work1.
-d port | --dataPort port
Data server or display server port to which viewers (for local deployments) or the data servlet (for web deployments) will connect in order to receive event data. If not specified, the default port (3278 for data servers and 3279 for display servers) is used.
-E | --purgeOnEdit bool
Specifies whether to purge all trend data when an instance is edited. bool is one of true and false. If this option is not specified, all trend data is purged when an instance is edited. In most cases this is the desired mode of operation.
-F arg | --filterInstance arg
Exclude instances which are not owned by user. This option applies to all dashboard processes. Default is false for the builder and true for the other dashboard processes.
Exception: when the Dashboard Viewer is connecting to a dashboard server, the default is true and cannot be overridden.
-f file | --logfile file
Full pathname of the file in which to record logging. If this option is not specified, the options in the log4j properties file are used. See also Text internationalization in the logs.
-G file | --trendConfigFile file
Trend configuration file for controlling trend-data caching.
-h | --help
Emit usage information and then exit.
-J file | --jaasFile file
Full pathname of the JAAS initialization file to be used by the data server or display server. If not specified, the server uses the file JAAS.ini in the lib directory of your Apama installation.
-L file | --xmlSource file
XML data source file. If file contains static data, append :0 to the file name. This signals Apama to read the file only once.
-m mode | --connectMode mode
Correlator-connect mode. mode is one of always and asNeeded. If always is specified all correlators are connected to at startup. If asNeeded is specified, the data server or display server connects to correlators as needed. If this option is not specified, the server connects to correlators as needed.
-N name | --name name
Component name for identification in correlator
-B logical-name:host:port | --namedServer logical-name:host:port
Sets the host and port for a specified logical data server name. This overrides the host and port specified by the Dashboard Builder for the given server logical name. This option can occur multiple times in a single command. See Working with multiple data servers for more information.
-O file | --optionsFile file
Full path of OPTIONS.ini
-P n | --maxPrecision n
Maximum number of decimal places to use in numerical values displayed by dashboards. Specify values between 0 and 10, or -1 to disable truncation of decimal places. A typical value for n is 2 or 4, which eliminates long floating point values (for example, 2.2584435234). Truncation is disabled by default.
-p port | --port port
Port on which this data server or display server will listen for management operations. This is the port used for communication between the server and the dashboard_management process.
-Q size | --queueLimit size
Set the server output queue size to size. This changes the default queue size for each client that is connected to the server.
-q options | --sql options
Configures SQL Data Source access. options has the following form:
[retry:ms | fail:n | db:name | noinfo |
nopererr | quote]
retry:: Specify the interval (in milliseconds) to retry connecting to a database after an attempt to connect fails. Default is -1, which disables this feature.
fail: Specify the number of consecutive failed SQL queries after which to close this database connection and attempt to reconnect. Default is -1, which disables this feature.
db: Specify the logical name of the database as specified in the builder's SQL options.
noinfo: Query database for available tables and columns in your database. If a Database Repository file is found, it is used to populate drop down menus in the Attach to SQL Data dialog.
nopererr: SQL errors with the word permission in them will not be printed to the console. This is helpful if you have selected the Use Client Credentials option for a database. In this case, if your login does not allow access for some data in their display, you will not see any errors.
quote: Encloses all table and column names specified in the Attach to SQL Data dialog in quotes when an SQL query is run. This is useful when attaching to databases that support quoted case-sensitive table and column names. If a case-sensitive table or column name is used in the Filter field, or you are entering an advanced query in the SQL Query field, they must be entered in quotes, even if the -sqlquote option is specified.
-R bool | --purgeOnRemove bool
Specifies whether to purge all instance data when an instance is removed. bool is one of true and false. If this option is not specified, all instance data is purged when an instance is removed.
-r bool | --cacheUsers bool
Specifies whether to cache and reuse user authorization information. bool is one of true and false. Specifying true can improve performance, because users are authorized only once (per data server or display server session) for a particular type of access to particular instance.
-s | --ssl
Dashboard data server only. Enable secure sockets for client communication. When secure sockets are enabled, the data server will encrypt data transmitted to Dashboard Viewers. Encryption is done using the strongest cipher available to both the data server and Viewer. SSL certificates are not supported. The display server does not support this option.
-T depth | --maxTrend depth
Maximum depth for trend data, that is, the maximum number of events in trend tables. If this option is not specified, the maximum trend depth is 1000. Note that the higher you set this value, the more memory the data server or display server requires, and the more time it requires in order to display trend and stock charts.
-t bool | --cacheAuthorizations bool
Cache and reuse instance authorizations. Caching authorizations is enabled by default. When caching is enabled, authorization checks are performed only once per user for each DataView they access. Disabling caching allows the current state of the DataView to be used in the authorization check, but can degrade performance.
-u rate | --updateRate rate
Data update rate in milliseconds. This is the rate at which the data server or display server pushes new data to deployed dashboards in order to inform them of new events received from the correlator. rate should be no lower than 250. If the Dashboard Viewer is utilizing too much CPU, you can lower the update rate by specifying a higher value. If this option is not specified, an update rate of 500 milliseconds is used.
-V | --version
Emit program name and version number and then exit.
-v level | --loglevel level
Logging verbosity. level is one of FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. If this option is not specified, the options in the log4j properties file will be used.
-X file | --extensionFile file
Full pathname of the extensions initialization file to be used by the data server or display server. If not specified, the server uses the file EXTENSIONS.ini in the lib directory of your Apama installation.
-x table-name:key-list | --queryIndex table-name:key-list
Add an index for the specified SQL-based instance table with the specified compound key. table-name is the name of a DataView. key-list is a comma-separated list of variable names or field names. If the specified DataView exists in multiple correlators that are connected to the dashboard server, the index is added to each corresponding data table. Example:
--queryIndex Products_Table:prod_id,vend_id
You can only add one index per table, but you can specify this option multiple times in a single command line in order to index multiple tables.
-Y | --enhancedQuery
Make SQL-based instance tables available as data tables for visualization attachments. See Attaching Dashboards to Correlator Data.
-z zone | --timezone zone
Default time zone for interpreting and displaying dates. zone is either a Java time zone ID or a custom ID such as GMT-8:00.  Unrecognized IDs are treated as GMT.  See Time Zone ID Values for the complete listing of permissible values for zone.
--inclusionFilter value
Set instance inclusion filters. Use this option to control scenario (for example, DataView) discovery. If not specified, all scenarios that have output fields will be discovered and kept in the memory of the dashboard processes, which can be expensive. For example, to include only the DV_Weather DataView, specify --inclusionFilter DV_Weather. The value can be a comma-separated list of scenario IDs. If you specify an inclusion filter, any specified exclusion filters are ignored.
--exclusionFilter value
Set instance exclusion filters. Use this option to exclude specific scenarios (for example, DataViews) from being kept in the memory of the dashboard processes. If neither exclusion filters nor inclusion filters are specified, all scenarios that have output fields will be discovered and kept in the memory of the dashboard processes, which can be expensive. The value can be a comma-separated list of scenario IDs. If an inclusion filter is specified, any exclusion filters are ignored.
--dashboardDir folder
Set the directory where display_server will be using to look for the deployed dashboards. If not specified, then display_server must be started from %APAMA_WORK%\dashboards directory in order for it to locate the deployed dashboards.
--dashboardExtraJars jarFiles
A semi-colon separated list of jar files for custom functions, custom commands or any other 3rd party jars (e.g. JDBC jar). If not specified, then the environment variable APAMA_DASHBOARD_CLASSPATH must be defined prior to running the dashboard processes. Each entry in jarFiles can be an absolute path of the jar file, or when --dashboardDir option is used, relative to the folder argument.
--namedServerMode
Dashboard data server only. Specify this option when you start a data server that is used as a named server by a display-server deployment. See Working with multiple data servers for more information.
--pidfile file
Specifies the name of the file that contains the process ID. This file is created at process startup and can be used, for example, to externally monitor or terminate the process.
It is recommended that the file name includes the port number to distinguish different servers. For example, correlator-3278.pid for a data server and correlator-3279.pid for a display server.