Command Line Options: Historian
The following command line arguments are enabled when you run the Historian from a Windows Command Prompt or UNIX terminal window. Options specified using command line arguments override values saved in initialization (e.g. OPTIONS.ini) files. See Starting the Historian for more information.
For command line options for your data source, refer to the RTView Data Sources section of this documentation.
Note: If a command line argument contains a space or a semicolon, then the entire argument must be enclosed in quotes (e.g.: "-sub:$data:my Data").
|
Name |
Description |
|||||||
|
|
Historian and Advanced Historian |
Advanced Historian Only |
||||||
|
-bg |
Set the RTView application to run as a background process. When this option is specified, the GmsLauncher process and run scripts exit immediately after the RTView application is started, rather than continuing to run, thereby reducing the host system process count. However, note that:
Note: This option is only recognized on the command line and is not read from, or saved to, any RTView options (.ini) files. Example: -bg |
|
||||||
|
-cachelast |
Store only the last (most recent) values in the cache for each unique data attachment. By default, the Historian stores all records in the cache each time the -cachesize or -cachetime limit is reached. This option allows the Historian to store less data than it receives, which can be useful in a configuration where the Historian receives data from the Data Server at a higher rate than necessary for historical storage. Example: -cachelast |
|
||||||
|
-cachesize: (records) |
Set the cache size. The Historian will cache the specified number of records and then commit them all to the database at one time. Example: -cachesize:50 |
|
||||||
|
-cachetime: (seconds) |
Set the cache time. The Historian will cache records for the specified number of seconds and then commit them all to the database at one time. Example: -cachetime:60 |
|
||||||
|
-charlimit |
Specify the maximum number of characters for a String column in a database table created by the Historian. The default is 50. This option allows the Historian to generate tables with larger String columns, rather than manually configuring each table. For example, in the command line: -charlimit:NNN and in HISTORY.ini: charlimit NNN where NNN specifies the maximum number of characters (for example, -charlimit:300). The Historian creates a VARCHAR column with the specified limit (for example VARCHAR(300)) for all String columns. However, be aware that each database vendor has a different upper limit on the maximum VARCHAR length. If you specify a charlimit value that is larger than the database vendor limit, errors might occur when the Historian creates a database table. Consult your database documentation for details. |
|
||||||
|
|
To store very long strings, you can specify MAX as the charlimit value rather than a number. For example, on the command line: -charlimit:MAX and in HISTORY.ini: charlimit MAX When MAX is specified as the value for the charlimit option, the type of database column created by the Historian for text columns depends on the specific database, as follows: Database: Column Type Declaration for charlimit=MAX HSQLDB: VARCHAR SQL Server: VARCHAR(MAX) Oracle: VARCHAR2(4000) DB2: CLOB MySQL: TEXT Each of these column types allows for the storage of very long strings. Consult your database documentation for details. |
|
||||||
|
-charlimitindex |
Specifies the maximum character length for text (VARCHAR) columns that are also index columns in the corresponding cache. For example, if the maximum character length is 70 (-charlimitindex:70), the Historian adds a VARCHAR(70) column to the database table it creates and persists to the cache for each text column that is an index column in a cache. If the charlimitindex property is not specified all text columns, including index text columns, use the size specified by the charlimit property. If the charlimit property is not specified, all text columns are created as VARCHAR(50). In the following example all index text columns are created as VARCHAR(70) and all non-index text columns are created as VARCHAR(200): run_historian -charlimit:200 -charlimitindex:70 Use the charlimitindex property in cases where the database limits the total width (in characters or bytes) that can be used in an index. Databases include DB2 and Oracle. |
|
||||||
|
-compactiontimerinterval |
|
Specifies the time interval, in seconds, for the compaction thread to sleep before checking for work. The default is 5 seconds. Example: -compactiontimerinterval:5 |
||||||
|
-compactionverbose:n |
|
Specifies whether and how to output to the console. There are three options: 0 - No information is output to the console. 1 - Summary information is output to the console. 2 - Debug-level information is output to the console. Example: -compactionverbose:1 |
||||||
|
-daemon |
Run the Historian as a daemon process. Note: This parameter must be the first command line argument given. Example: run_historian -daemon |
|
||||||
|
-dbname:(name) |
Set the name of the history database. Note: This name must match the name of the history database configured in the Display Builder's Application Options> SQL Tab. Example: -dbname:RTVHISTORY |
|
||||||
|
-exit_on_out_of_memory |
Force the Historian to terminate when an OutOfMemoryException occurs. This option is intended for use in a HA deployment where a backup server is available, otherwise the process may continue to run in a crippled state and prevent the backup from taking over. Note: The Historian is not automatically restarted by this option and must be restarted manually. Example: -exit_on_out_of_memory |
|
||||||
|
filename |
Add a data configuration (.rtv) file to the Historian. Example: run_historian config.rtv |
|
||||||
|
-index_history_tables |
When this option is set to true, the Historian creates two indexes on each database table that it creates to persist cache history. One index uses the cache's timestamp column, the other index uses the cache's index columns plus its timestamp column. If the cache has no index columns defined, then only the first index is created. For large tables, this can improve the performance of SQL queries that RTView executes to retrieve cache history data from the database. Command Line Example: -index_history_tables:true HISTORY.ini File Example: index_history_tables:true |
|
||||||
|
-insertcolumnnames |
Include column names in the database insert statements for user-defined tables. This is useful when the Historian is adding data to existing tables and the column order is not an exact match or the insert statement contains a subset of the existing table columns. Note: This option does not apply to the HISTORY and HISTORY_S tables. Example: -insertcolumnnames |
|
||||||
|
-jmxport:(port number) |
The port number to use to expose JMX methods to monitor and manage the Historian. There is no default port. If not specified, these JMX methods will not be accessible. See Managing the Historian Using JMX for more information. Example: -jmxport:9996 |
|
||||||
|
-local_backlog |
If enabled, allows the Historian to use its local heap space to temporarily store a backlog of data that is subsequently stored in the database. If not enabled, the backlog of data is kept in the Data Server, where it might be discarded after a relatively brief period of time if the Historian is unable to process it. Use this property to help avoid loss of data during busy periods when the Historian receives data from a Data Server at a higher rate than it can be stored in the database. By default the local_backlog property is not enabled. The local_backlog property keeps a minimum of 50,000 rows of data. If the Oracle server JVM is used, the backlog grows as large as the available heap space allows. |
|
||||||
|
|
The following message appears in the Historian log each time the backlog increases by 1000 rows: backlog: increased to N rows or decreases by 1000 rows: backlog: decreased to N rows where N is the current number of rows in the backlog. If the incoming rate of data exceeds the rate at which data can be stored in the database for an extended period of time, the backlog may need to be trimmed in order to avoid an OutOfMemory exception in the Historian. If that occurs, the following message appears in the Historian log: backlog: discarded N rows If this message is seen frequently, it may be necessary to adjust the Data Server, Historian, and/or database configuration to either reduce the incoming data volume or increase database throughput. Example: run_historian -local_backlog Properties File Example: sl.rtview.historian.local_backlog=true |
|
||||||
|
-log4j |
Turns on Log4j logging for the RTView application. By default, RTView processes print log messages to the console. To obtain log files, redirect the RTView application output and error streams to a log file using Log4j. After starting Log4j, the first time-stamped row in the log file appears as follows: 2012-02-02 14:00:54,693 INFO – [rtview] Log4j is being used with sl.log4j.properties as the configuration file. When Log4j is not in use, the first time-stamped row in the log file appears as follows: 2012-02-03 10:40:31.866 [rtview] Logging redirected for System.out and System.err. Log4j is not in use. (Note the missing INFO column when Log4j is not in use.) For example: run_historian –log4j run_historian –log4j –log4jlevel:INFO –showlogcat |
|
||||||
|
|
To run the Historian as a background process using the -bg command line argument, use the sl-bg.log4j.properties configuration file (which only outputs to a log file rather than to a console) and the -daemon argument. -bg (background) example: run_historian -daemon –bg –log4j –log4jprops:sl-bg.log4j.properties Note: The logging method from previous versions of RTView does not use Log4j. This previous method of logging is enabled with -logfile and –logdir and is still supported. Do not use both the previous logging method and Log4j or you receive the following error message: ERROR: log4j configuration ERROR - com.sl.rtview.useLog4j is set to true but -logfile redirection is in use. Log4j will not be used. -showlogcat - Turns on the Category column in the log file output. When not in use, the Category column is not shown in the log file. When not in use, the Category column is not shown in the log file. For example: -showlogcat |
|
||||||
|
|
-log4jprops - Specify the .properties file to use to format the Log4j log file. By default, sl.log4j.properties is used. Use this to provide a different property file name. The .properties file is searched for inside a .jar/.war file, then searched for in the current directory, and lastly searched for in the %RTV_HOME%/lib directory. The filename can have a path preceding it. For example, C:\mydir\my.log4j.properties. For example: -log4jprops:mylogfile.properties |
|
||||||
|
|
-log4jlevel - Specify the Log4j Level. INFO is used by default. Valid values are: FATAL: Indicates a severe error that likely causes the application to abort. ERROR: Indicates an event that might not cause the application to abort. WARN: Indicates a potentially harmful event. DEBUG: Indicates detailed informational about events for debugging the application. INFO: Indicates informational messages about the progress of the application at coarse-grained level. For example: -log4jlevel:INFO |
|
||||||
|
-logdir |
Specify to prefix the log file name that is set in the -logfile option to the directory name in which the log file is stored. If the -logfile option is not specified, this option is ignored. Note: This option is only recognized on the command line and is not read from, or saved to, any RTView options (.ini) files. Example: -logdir:ABCcompany |
|
||||||
|
-logfile |
Specify the redirection of output and error messages to a file. The RTView application output and error message streams are redirected to the specified file. The file is created if it does not exist. If the file does exist, its previous contents are cleared. Note: This option is only recognized on the command line and is not read from, or saved to, any RTView options (.ini) files. Example: -logfile:Historian.log |
|
||||||
|
nogui |
Specifies to run the Historian as a daemon process. Note: This parameter must be the first command line argument given. Example: run_historian -nogui |
|
||||||
|
-noreset |
Do not clear database tables before storing new data. Example: -noreset |
This option does not apply to the Advanced Historian. |
||||||
|
-persistCaches:true |
Allows the Historian to receive rows of cache data to be stored from the cache data source (via the data server, if in use) after the processing and primary compaction have already been performed. The Historian also queries the cache data source (via the data server, if in use) for the caches that should be persisted, thus avoiding the need for the Historian to load the cached data files as Historian data configuration files. You can enable the this option by using one of the following options:
-persistCaches:true
persistCaches true Note: When this option is enabled, the Historian will continue to load any files that appear in the Data Configuration Files list or that are listed as history_config lines in the HISTORY.ini file, even if those files contain cache definitions. So, if you use persistCaches in an existing configuration, you should remove those files from the list of Data Configuration Files or from the HISTORY.ini file. Otherwise, data for caches defined in those files will get stored twice. |
|
||||||
|
-persistInitTimeRange |
Specify a time range for the historian to get cache history data from the Data Server. Normally, when the cache persistence feature is enabled in the historian, the historian begins collecting cache history data starting at the time when each Data Server connects. This is adequate in most situations. The persistInitTimeRange option specifies a time range, in seconds, back from the current time for the historian to get cache history data from the Data Server. This is useful if the historian is started after the Data Server. In this case the Data Server collects cache history that has not been sent to the historian. For example, if the Data Server was started an hour before the historian, you could start the historian so that it requests an hour of cache history from the Data Server. For example: run_historian -persistCaches:true -persistInitTimeRange:3600 |
|
||||||
|
-processName |
Specify to identify applications running as background processes. This option tags a unique identifier onto RTView server instances, enabling you to differentiate between multiple instances of those RTView applications. This option allows you to stop a particular instance without eliminating the other instances. If no process name is specified, the RTView application name is used as the process name. For example, run_builder -processName:XX adds the following JVM option to the Java call: -DPROCESS_NAME=XX Where XX is the value you specified for the -processName argument. Note: Values with spaces cannot be used for this option on Unix. Example: -processName:XX |
|
||||||
|
-rebuildtables |
On startup, delete all existing Historian tables (including HISTORY and HISTORY_S) and recreate them. Example: run historian -rebuildtables It is also possible identify specific tables to rebuild (i.e. delete and recreate). Note: Table names are case-sensitive and may not contain spaces. Example: -rebuildtables:Table1,Table2,Table3 Note: User-defined tables will be rebuilt as data is received for each table. |
Do not use -rebuildtables in conjunction with the -smoothCompaction option because older data will be lost when the Historian tables are rebuilt. |
||||||
|
-retention |
Specify (in minutes) the length of time records can exist before they are deleted. Example: -retention:5 |
In the Advanced Historian, compactionRules specify how long records can exist before they are compacted or deleted. Go to Caches> Introduction> Historian Properties. |
||||||
|
-retentionChunkSize |
|
This option allows you to delete excess accumulated history rows in “chunks” of time (oldest rows deleted first) rather than deleting the data all at one time. Valid values are: y = YEAR M = MONTH w = WEEK d = DAY h = HOUR m = MINUTE s = SECOND Values can be as short as 1m (minute) or as long as 99y (years). For example: -retentionChunkSize:2d In the example above, history rows marked for deletion are broken down into 2 day “chunks” and deleted one after the other until all the rows in the “chunks” have been deleted. |
||||||
|
-retentionMax |
Specify (in minutes) the maximum length of time that may pass before retention processing is performed. Note: If the -retention time set is shorter than the specified -retentionMax, then the record's retention span is used. Example: -retentionMax:60 |
Specify (in minutes) the maximum length of time that may pass before retention processing is performed -- this setting only applies to the compaction rule with the longest retention amount. For tables that do not have compactionRules set, this option defaults to basic Historian behavior. Note: If the span of the compaction rule with the longest retention amount is shorter than the specified -retentionMax, then the compaction rule span is used. Example:- -retentionMax:60 |
||||||
|
-smoothcompaction |
|
Based on specified compactionRules, perform compaction on old data that currently exists in your database from prior executions of the Historian. Do not use the -rebuildtables option in conjunction with -smoothCompaction because older data will be lost when the Historian tables are rebuilt. table1,table2 - Specifies which tables to apply smooth compaction, where table1 and table2 are the table names. Any number of valid tables can be specified. Example: -smoothcompaction:table3,table4 Note: This option is not recommended if the Historian has a heavy load of data to process or the Historian database is being used by other applications. |
||||||
|
-smoothCompactionRecent |
|
Specify how far back in time the smoothing process is applied. The format is: -smoothCompactionRecent:NN Where NN is '1d' or '1w'. Example: -smoothCompactionRecent:1w |
||||||
|
-smoothingonly |
|
When -smoothcompaction is also specified, enables compaction to be performed while no data updates are available. Example: -smoothingonly |
||||||
|
-stringColMaxLen |
Specify a limit on the length of a string from a cache table column that is stored in the database. If a string is longer than the specified limit, it is truncated to the limit before being stored in the database table. This can avoid SQL exceptions encountered when the length of a string exceeds the capacity of the column's data type (for example, 4000 characters in an VARCHAR2 column in Oracle). This can be specified in HISTORY.ini as follows: stringColMaxLen 3500 It can also be specified on the command line or a properties file. By default the property has no value (no limit is enforced). Example: -stringColMaxLen:3500 |
|
||||||
|
-sub: (substring:subvalue) |
Add a substitution string/value pair. Multiple substitution pairs can be specified on the command line. Note: Substitution strings cannot contain the following: : | . tab space , ; = < > ' " & / \ { } [ ] ( ) If your substitution value contains single quotes, you must escape them using a /. Example: -sub:$data:myData -sub:$filter:Plant=/'SanFrancisco/' |
|
||||||
|
-tablename: (tablename) |
Specify the table name to use when archiving scalar data. The table is created if it does not exist. If this option is not specified, the table name HISTORY is used by default. If __none is specified, then no table is created for storing scalar data. (If the Historian is used only to persist RTView cache data, then no scalar data is stored anyway). Example: -tablename:MY_TABLE Example: -tablename:__none |
|
||||||
|
-timestamp: (type) |
Specify the type of timestamp. There are three options: none - No TIMESTAMP column is stored. sql - A single TIMESTAMP column is stored using a standard SQL TIMESTAMP data type. str - Two TIMESTAMP columns are stored with each record as strings. Example: -timestamp:sql |
|
||||||
|
-timezone |
Set the default timezone for interpreting and displaying dates. Include a Java timezone ID or a custom ID, such as "GMT-8:00". Unrecognized IDs will be treated as GMT. See Timezone ID Values for more information. If you run the RTView Builder with a valid timezone parameter and then save Application Options, the timezone information will be persisted. To prevent the persisted timezone value from being used, pass "none" as the timezone ID. Example: -timezone:US/Eastern -timezone:none |
|
||||||
|
-u(milliseconds) |
Set update rate in milliseconds. Default is 2000. Example: -u5000 - updates every 5 seconds |
|
||||||
|
-verbose |
Set the Show Data in Console flag to true so that a line is printed to the console for each record that is stored in the database. Example: -verbose |
|
||||||
|
-version |
Prints the RTView application version information and exits immediately. Example: run_historian -version |
|
||||||
Options Enabled with Alerts
In addition to the General Options, the following command line arguments are enabled with the Alert data source. See Alerts and Audit Alert Action for more information.
|
Name |
Description |
|||||||||
|
-actionauditdb:(database) |
Specifies name of a database connection, as defined on the SQL tab, in which to store Audit Alert Action information. Example: -actionauditdb:ALERTBD |
|||||||||
|
-actionaudittable:(table) |
Specifies name of the table in the Alert Action Audit Database in which to store the Audit Alert Action information. Example: -actionaudittable:ACTION_AUDIT_TABLE |
|||||||||
|
-alertcleartime: (number of seconds) |
Specifies the rate, in seconds, to remove cleared alerts. Example: -alertcleartime:3 |
|||||||||
|
-alertds:alertdef:(filename) |
Adds an alert definition file. Cannot specify substitutions. To specify substitutions, use the Application Options - Alerts tab. Example: -alertds:alertdef:myalerts.rtv |
|||||||||
|
-alertds:enabled:(true or false) |
Enables/disables all alerts in the active alert definition files. Example: -alertds:enabled:false |
|||||||||
|
-alertds:history:(size of table) |
Sets the number of rows that are stored in the AlertTable. Example: -alertds:history:1000 |
|||||||||
|
-alertinitdelay:(number of seconds) |
Specifies the duration, in seconds, to wait after startup to begin executing alerts. Example: -alertinitdelay:5 |
|||||||||
|
-enableactionaudit:(true or false) |
If true and configured, alert actions will be stored to the specified database table. Example: -enableactionaudit:true |
|||||||||
|
-exitOnPersistInitFailed |
Specifies what occurs when alert persistence is enabled but cannot be initialized due to a database problem or configuration issue. When false (the default setting), RTView initializes the alerts with persistence disabled. This is consistent with the behavior in releases previous to RTView 6.6.0 and Enterprise Monitor 2.2.0. When true, RTView exits after the persistence initialization has failed without initializing the alerts. Example: -exitOnPersistInitFailed:true |
|||||||||
|
-ignorelutforcount:(true or false) |
If true, the AlertTable Count column increments for an alert when new data is received even if the Last Update Time has not changed. This can cause invalid Counts for alerts attached to caches. If false or not specified, the AlertTable Count column increments for an alert only if the Last Update Time has also updated. This is the default behavior. Example: -ignorelutforcount:true |
|||||||||
|
-lutupdatesnewdata:(true or false) |
Enables\disables updates to the AlertTable when New Data Only is selected and to the Alert Persistence database when the only columns that contain changes for that row are Last Update Time and Count. By default, the Last Update Time and Count columns are not tracked by the Row Update Time column. To track the updates of the two columns in the Row Update Time column, use the -lutupdatesnewdata command line option. See Attach to Alert Data and Viewing Alerts for more information. Example: -lutupdatesnewdata:true |
|||||||||
|
-multipleindexdelim:(string) |
For alerts with multiple index columns, create a unique alert index by concatenating all of the index column values. Value can be any string, except the following:
Default is tilde (~). Example: -multipleindexdelim:~ |
|||||||||
|
-persistInitDelayTime: (number of seconds) |
Specify the amount of time, in seconds, to delay a backup Data Server from reading the alert persistence database during a failover. The default is 5 seconds. Increase the amount of time if the persistence database is slow or if you expect a large number of alerts to change on each update period. Otherwise, there might not be enough time for the failing Data Server to write all the alerts to the database before the backup server reads them. Note: Even with high availability configurations, there are cases in which some alerts might not be persisted. For example:
In cases where alerts are not persisted, the new primary Data Server generates new alerts if the data is still in an alert state. The new primary Data Server might also re-use ID's that were used by the failed Data Server. Example: -persistInitDelayTime:10 |