CWMS Client Debug Logging and "-D" Flag Options
CWMS Client applications utilize the Java Util Logging framework to provide various levels of information to the end user, reporting on the execution of the application. The logged messages are output to handlers which are implemented as log files on the client file system, messages in the console window, and, in the case of the CAVI, in a dedicated Messages tab. Detailed documentation on the logging framework can be found here: https://docs.oracle.com/en/java/javase/11/core/java-logging-overview.html.
Properties File Configuration
The Java Util Logging framework provides the ability to tune how verbose the logged messages should get broadcast to those handlers using a Java Properties file named logging.properties. In each of the application executables' config files (ex. CAVI.config) there is a line vmparam -Djava.util.logging.config.file that specifies the location of the properties file.
The CWMS client distribution bundle contains default properties files with the log levels targeted for end user informational messages. When issues arise, the HEC production support team will generally ask for logs to be set to debug levels and will provide the client with an updated properties file targeting specific pieces of the software to help diagnose the cause of the issue. Whenever this happens, it is important to retain the original properties file in order to revert back to default logging levels.
CAVI
The CAVI.config by default points the logging properties file to the default configuration under <cwms installer>/CAVI/config/properties/logging.properties. If the client has a personal config setup (defined by the line in the CAVI.config file include $APPDATA\CWMS\PersonalConfigs\CAVI-Personal.config) to override that default location, make sure the correct properties file gets updated. A guide to set up a Personal Config is available here.
| App | Exe config | Configuration parameter | Default file location |
|---|---|---|---|
| CAVI | CAVI.config | vmparam -Djava.util.logging.config.file | <cwms installer>/CAVI/config/properties/logging.properties |
Common Executables
The common executables under <cwms installer>/common/exe have a common executable configuration called ~common.config that contains the vmparam -Djava.util.logging.config.file property definition. By default this points to the file <cwms installer>/common/config/properties/logging.properties though can similarly be overridden through a personal config just like the CAVI.
| App | Exe config | Configuration parameter | Default file location |
|---|---|---|---|
CWMSVue ServerAdmin DataExchange DSSVue ConfigEditor Jython LogFileViewer | ~common.config | vmparam -Djava.util.logging.config.file | <cwms installer>/common/config/properties/logging.properties |
Logging Properties Configuration
The logging.properties file contains properties that can fine tune how log messages are broadcast and handled. Levels on individual loggers can be configured to broadcast to the handlers, and handlers can be configured with the level of logs they are able to consume. Adjusting these levels requires knowledge of the relevant applications and the settings to tweak are provided by the HEC production support team. For further documentation see https://docs.oracle.com/cd/E57471_01/bigData.100/data_processing_bdd/src/rdp_logging_config.html
Logging levels
The logging level specifies the amount of information that is logged. The levels (in ascending order of verbosity) are:
- SEVERE — Indicates a serious failure. In general, SEVERE messages describe events that are of considerable importance and which will prevent normal program execution.
- WARNING — Indicates a potential problem. In general, WARNING messages describe events that will be of interest to end users or system managers, or which indicate potential problems.
- INFO — A message level for informational messages. The INFO level should only be used for reasonably significant messages that will make sense to end users and system administrators.
- CONFIG — A message level for static configuration messages. CONFIG messages are intended to provide a variety of static configuration information, and to assist in debugging problems that may be associated with particular configurations.
- FINE — A message level providing tracing information. All options, FINE, FINER, and FINEST, are intended for relatively detailed tracing. Of these levels, FINE should be used for the lowest volume (and most important) tracing messages.
- FINER — Indicates a fairly detailed tracing message.
- FINEST — Indicates a highly detailed tracing message. FINEST should be used for the most voluminous detailed output.
- ALL — Enables logging of all messages.
"-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 |