HEC-RTS Debug Logging and -D Flag Options
HEC-RTS uses the Java Util Logging framework to provide users with detailed execution information. Log messages are sent to various handlers, including log files, the console window, and the Messages tab within HEC-RTS. For more on Java logging, see the official documentation.
This guide will show you how to configure and manage logging in HEC-RTS using the Java Util Logging framework, including setting log levels, using properties files, and working with application-specific configurations.
Configuration with Properties Files
Logging behavior is controlled by a logging.properties file, defined in each executable's config file (e.g., CAVI.config) using the vmparam -Djava.util.logging.config.file parameter. The HEC-RTS bundle includes default property files set for standard informational logging. If deeper troubleshooting is needed, HEC support may provide a custom properties file to enable more detailed logs. Always back up the original file before making changes.
CAVI Configuration
By default, CAVI.config points to <HEC-RTS version>/CAVI/config/properties/logging.properties. If a Personal Config is set (via include $APPDATA\CWMS\PersonalConfigs\CAVI-Personal.config), make sure updates are made to the correct logging file.
A guide to setting up a Personal Config is available here.
Common Executables
The ~common.config file under <HEC-RTS version>/common/exe sets logging for shared components, typically pointing to <HEC-RTS version>/common/config/properties/logging.properties. This, too, can be overridden via personal configs.
Logging Properties Configuration
The logging.properties file defines:
- Which loggers broadcast messages
- Which handlers receive and display those messages
- What level of detail is logged
Only adjust these settings if instructed by HEC support. For more on tuning logs, refer to this guide.
Logging levels
The levels (least to most verbose) are:
- SEVERE — Critical failures preventing normal execution
- WARNING — Potential issues of interest to users or admins
- INFO — Key informational messages
- CONFIG — Static configuration details
- FINE — Basic tracing messages
- FINER — More detailed tracing
- FINEST — Highly detailed output
- ALL — Logs everything
Use detailed levels (e.g., FINER, FINEST) with caution—they generate large log files. Always target specific loggers to avoid excessive output.
-D Flag Options
| Property Name | Input Type (Boolean, String) | Component | Description | Default setting in CAVI.config/Example |
|---|---|---|---|---|
| LooseVersionCheck | Boolean | Cavi/Server Jars | If set true, will not compare all server jars' versions to client jars' versions | vmparam -DLooseVersionCheck=true |
| Disable.DbfFileHandling | Boolean | CWMS | If set true, DBF files will not be uploaded to the servers. This is needed because there is not a 64-bit codebase library that can be used on the servers. | vmparam -DDisable.DbfFileHandling=true |
| LOGFILE | String | CWMS | The file path to application's console/log file | vmparam -DLOGFILE=$TEMP/logs/cavi.log |
| CACHE_DIR | String | CWMS | The file path to the application's cache directory | vmparam -DCACHE_DIR=$APPDATA\CWMS\pythonCache |
| LogFileHasPid | Boolean | CWMS | Allows multiple instances of CAVI running simultaneously to write unique log files, identified by the process ids. Note - there will be a new log file each time CAVI is run. | vmparam -DLogFileHasPid=false |
| DataSetValidParameterListFile | String | CWMS | File location for the parameters_units.def | vmparam -DDataSetValidParameterListFile=..\config\parameters_units.def |
| UNIT_FILE | String | CWMS | File location of the unitConversions.def file | vmparam -DUNIT_FILE=..\config\unitConversions.def |
| CWMS_HOME | String | CWMS CAVI | CWMS home directory location | vmparam -DCWMS_HOME=. |
| NoDxXsdValidation | Boolean | CWMS | If true, will not validate XML files | vmparam -DNoDxXsdValidation=true |
| PLUGINS | String | CWMS | The paths to be searched when finding plugins. | vmparam -DPLUGINS=../shared/jar/ext;jar/ext |
| AsciiSerializer.formatFile | Boolean | CWMS | If set true, The ASCIISerializer will format and indent the files it writes. The formatted files are more readable but also larger. | vmparam -DAsciiSerializer.formatFile=true |
| CWMS_EXE | String | CWMS | File path to the cavi.exe | vmparam -DCWMS_EXE=..\ |
| cwms.db.impl.classpaths | String | CWMS | File path to the CWMS DBI Impl | vmparam -Dcwms.db.impl.classpaths=jar/cwmsDbApi/jooq |
| Teaming.CwmsServers | Boolean | CWMS | When true, allows storage of a Team Watershed on the CWMS servers | vmparam -DTeaming.CwmsServers=true |
| USE_TABBED | n/a | CWMS | When specified in the application's config file, the framework will use tabs instead of dropdowns for modules | vmparam -DUSE_TABBED |
| oracle.metrics.clientid | String | CWMS | Used to identify which application is connecting to Oracle | vmparam -Doracle.metrics.clientid="CWMS CAVI Connection" |
| cavi.netbeans.platformdir | String | CWMS | Turn on the CAVI Dashboard, location of Dashboard software | vmparam -Dcavi.netbeans.platformdir=./module/Dashboard |
| UseEmbeddedDssVue | Boolean | CWMS | When true, an embedded DSSVue is used instead of the installed version. | vmparam -DUseEmbeddedDssVue=true |
| cwms.connection.persist | Boolean | CWMS | When true, instructs the application to perform keep-alive pings on connections to the Oracle database. | commented out in cavi.config file vmparam -Dcwms.connection.persist=true |
| cwms.connection.recycle.seconds | Numeric | CWMS | Allow for non-default timing to be used for the keep-alive. Controls how often the check for keep-alive occurs, it defaults to 300 seconds, 5 minutes. | commented out in cavi.config file vmparam -Dcwms.connection.recycle.seconds=300 |
| cwms.connection.refresh.timeout.seconds | Numeric | CWMS | Sets the maximum amount of time that will occur before an idle connection has a keep-alive performed. This defaults to 150 seconds, 2.5 minutes. | commented out in cavi.config file vmparam -Dcwms.connection.refresh.timeout.seconds=150 |
| noServerSideSecurity | Boolean | CWMS | When true, disables server side access control list checks for the RMI File Manager. Needed on the controlling node for WAT Distributed Computes. | commented out in cavi.config file vmparam -DnoServerSideSecurity=true |
| schedulerEntries.directory | String | CWMS | Location directory of CWMS scheduler files | vmparam -DschedulerEntries.directory=$APPDATA\CWMS\CAVI\scheduler |
| Login.hasPassword | boolean | CWMS | When true, a password field is shown on the login dialog. When unspecified or false the login supports CAC only. | vmparam -DLogin.hasPassword=true |
| Has2_1Importer | boolean | CWMS | When set to true, the 2.1 Import option is enabled in the New Watershed dialog | vmparam -DHas2_1Importer=false |
| Teaming.ShowDeleteNotification | boolean | CWMS | When true, the deleted/removed messages will be displayed. The default behavior now is to hide all messages regarding deleted/removed files from the CAVI "Team" tab, the "purple pop-up" messages and the console output. | vmparam -DTeaming.ShowDeleteNotification=false |
| OpenLastWatershed | boolean | CWMS | When true, the last project by version (by editing the .config file) is open. So for 3.1.1 they can load the last watershed, but in 3.2 they can set the -D flag =false and it won't load the last watershed, there by avoiding having it converted to the latest version. if its set to either true or false it overrides what the user selected in the Options dialog. If its not in the config file at all (which is the default) then nothing changes. | vmparam -DOpenLastWatershed=true |
| regi.netbeans.platformdir | String | REGI Tools | Location of REGI Tools Netbeans platform directory | vmparam -Dregi.netbeans.platformdir=jar/regitools/regitoolsparent |
| hec.data.cwmsRating.RatingSet.databaseLoadMethod | Strings; EAGER, LAZY, and REFRENCE | Ratings | Sets a global behavior for the rating's database retrieval: EAGER: retrieve all of the rating curves from the database LAZY: only retrieve the rating curves from the database when they are needed (default setting) REFERENCE: retrieve no rating curves from the database and instead perform all operations using the DB Ratings API. | vmparam -Dhec.data.cwmsRating.RatingSet.databaseLoadMethod=eager |
| COLLECTION | n/a | DSS | When specified the DSS collections data features are enabled | vmparam -DCOLLECTION |
| scripts.directory | String | CWMSVue/DSSVue | DssVue and CWMSVue script file locations (in CAVI.config) | vmparam -Dscripts.directory=$APPDATA/HEC/HEC-DSSVue/scripts |
| MonitorEDT | boolean | CWMSVue | When true, turns on the MonitorEdtQueue class. Identifies what calls are causing the UI to become unresponsive due to threading | vmparam -DMonitorEDT=false |
| LogEDT | boolean | CWMSVue | When true, turns on the LogViolationRepaintManager class. This class logs UI calls that are improperly accessed by background threads. | vmparam -DLogEDT=false |
| http.agent | String | Map | Sets the http agent to a recognizable browser for the internet map sites | vmparam -Dhttp.agent="Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0)" |
| statePlane.directory | String | Map | File location of the state plane directory for mapping | vmparam -DstatePlane.directory=..\config |
| MapPanel.NoVolatileImage | Boolean | Map | Disables VolitileImages in the MapPanel solving bad graphical glitches as well as Direct3D for 1.6 Update 10 compatibility. | vmparam -DMapPanel.NoVolatileImage=true |
| ShowAllElementsInMenu | Boolean | Map | When selecting an element in the Modeling Tab's map window, show all elements associated with the map location if set to true | Not in cavi.config vmparam -DShowAllElementsInMenu=true |
| HasShapeMapTool | Boolean | Map | Adds the Shape Map Tool to the Wat Map Schematic | vmparam -DHasShapeMapTool=true |
AlternateFrameLayout | Boolean | UI | If set true, the Watershed panel will appear on the right and the tabs along the left instead of the bottom | vmparam -DAlternateFrameLayout=true |
| UseWindowsLnF | Boolean | UI | When set to true, enables the Windows look and feel on Windows. When set to false, or unset, uses the default system look-and-feel (usually Metal) | vmparam -DUseWindowsLnF=true |
| DEBUG_RASSERVERS | Boolean | RAS Plugin | When set true, when debugging RAS, RAS will not be started by CAVI, it will start by an external process | vmparam -DDEBUG_RASSERVERS=true |
| Launcher.quietMode | Boolean | RAS Plugin | When set true, passes -q to the javaStarter that disables any message boxes | vmparam -DLauncher.quietMode=true |
| RasPlugin.NoRasCallbacks | Boolean | RAS Plugin | If set true, disables RAS callbacks used for progress bars | vmparam -DRasPlugin.NoRasCallbacks=true |
| RasPlugin.DebugOutput | Boolean | RAS Plugin | When set true, output is passed through the RAS Plugin to the main (CAVI) application's log | vmparam -DRasPlugin.DebugOutput=true |
| RasPlugin.ServerLookupTries | Numeric | RAS Plugin | Controls how many times the RAS plugin will try to connect to RAS before giving up | vmparam -DRasPlugin.ServerLookupTries=10 |
| RasPlugin.ServerWaitMs | Numeric | RAS Plugin | How long to wait between each attempt to connect to RAS in milliseconds | vmparam -DRasPlugin.ServerWaitMs=100 |
| ClientCheckInURL | String | RAS Plugin | Overrides the client check-in URL passed to the other process for the plugin used for shutting down if CWMS dies | vmparam -DClientCheckInURL=//127.0.0.1:8686/CAVI |
| RasPlugin.exe.dir | String | RAS Plugin | Location of the javastarter.exe to start the RAS Plugin. Defaults to user.dir | vmparam -DRasPlugin.exe.dir=..\ |
| python.path | String | Python | Directory path to jython jars | vmparam -Dpython.path=..\jar\sys\jython-standalone-2.7.0.jar\Lib;..\jar\jythonDbApi-v4.1-dev.jar |
| python.home | String | Python | Directory location for Python home | vmparam -Dpython.home=..\ |
| python.cachedir.skip | Boolean | Python | If set true, Reduces the NameErrors from occurring in Jython scripts that use wildcard imports | vmparam -Dpython.cachedir.skip=true |
| javax.net.ssl.cwms.keyStoreType | String | Java/CWMS | Enable SSL for CWMS Java KeyStore | vmparam -Djavax.net.ssl.cwms.keyStoreType=JKS |
| java.security.policy | String | Java | File path to java security policy | vmparam -Djava.security.policy=jar:file:jar/rmadev.jar!/com/.java.policy |
| java.rmi.server.hostname | Numeric | Java | IP of the rmi server | vmparam -Djava.rmi.server.hostname=127.0.0.1 |
| com.sun.media.jai.disableMediaLib | Boolean | Java | If true, will disable mediaLib searching that produces unwanted errors | vmparam -Dcom.sun.media.jai.disableMediaLib=true |
| javax.net.debug | Boolean | Java | Set to true to turn on to debug SSL connections | commented out in cavi.config vmparam Djavax.net.debug=true |
| java.util.logging.config.file | String | Java | Logging settings to CWMS\config\properties | vmparam -Djava.util.logging.config.file=./config/properties/logging.properties |
| jna.tmpdir | String | Java | Directory location for JNA to extract its files to | vmparam -Djna.tmpdir=C:/Temp/cwms/temp |
| sun.rmi.server.exceptionTrace | Boolean | Java | This property controls the output of server-side stack traces from exceptions and errors that are thrown by dispatched, incoming remote calls. If this value is true, exception stack traces will be printed. | vmparam -Dsun.rmi.server.exceptionTrace=true |
| java.rmi.server.hostname | Numeric | Java | The RMI server hostname/IP | vmparam -Djava.rmi.server.hostname=127.0.0.1 |
| oracle.caching.openallconnections (Can be removed in 3.3.x. No longer used) | Boolean | Oracle | If set to true, use loopback so that the Corps PC firewall doesn't keep the CAVI from communicating to the plugins | vmparam -Doracle.caching.openallconnections=true |
| sun.java2d.nodraw | Boolean | Java | When true, sets Java to not use hardware acceleration. Some multiple monitor configurations display CAVI windows as black screens when dragging between monitors, because the monitors are using different video cards. Java SE 6 Update 10, which contains a new implementation of D3D support. (Setting sun.java2d.noddraw=true is now interpreted exactly the same as disabling that via sun.java2d.d3d=false.) | vmparam -Dsun.java2d.nodraw=true |
| com.sun.media.jai.disableMediaLib | Boolean | Java | If true, turns off the MediaLib functionality. Used for 32-bit libraries to help load the internet maps faster | vmparam -Dcom.sun.media.jai.disableMediaLib=true |
| java.library.path | String | Java | File path to java library | vmparam -Djava.library.path=../shared/lib64 |
| prism.order | String | Java | Turn on software rendering for JavaFX | vmparam -Dprism.order=sw |
DLogPluginCalls | Boolean | Java | turn on logging of API calls to the plugins. Configuring the config/properties/logging.properties lets you define what you want to log. Add -D to CAVI.config file and have the logging.properties file line in the cavi.config uncommented (also replace the relative path with the full path to the logging.properties file on the line) hec2.util.InterfaceLogProxy.All.level = FINE -logs the entry and exit. hec2.util.InterfaceLogProxy.All.level = FINER -logs the entry and exit, parameters passed in and return value hec2.util.InterfaceLogProxy.All.setDataLocations.level = FINER -would log just the calls to setDataLocations hec2.util.InterfaceLogProxy.RasPluginClient.setDataLocations.level = FINER -would log just the calls to the RAS plugin's setDataLocations | vmparam -DLogPluginCalls=true |
DisableTCUAgreement | Boolean | java | If set to true, will prevent TCU messages from appearing to user on launch | vmparam -DDisableTCUAgreement=false |
HmsSaveToBase | Boolean | HEC-HMS Plugin | If set to true, the ability to use the "Save to Base" in HEC-RTS is enabled. By default, this is set to false. | vmparam -DHmsSaveToBase=false |