LOGGING
Overview
SLF4J (https://www.slf4j.org) for all of our logging statements. This allows for the use of different loggers depending on the exact usage of OpenDCS.
The packaged applications (released zip and docker containers) will use logback (https://logback.qos.ch/).
Configuration
A default logback.xml configuration is provided in $DCSTOOL_HOME/logback.xml. If $DCSTOOL_USERDIR/logback.xml is present then it is used as-is.
- The default logback configuration files outputs OpenDCS logging messages at the set log level to a file and
standard error. Logging statements from dependencies will be at info. Additionally logs will be rotated daily and kept for 7 days, with a maximum total size of 3 GB allowed.
The command parameters of -l and -d will continue to work, at least on unix style systems, as before and will be translated to the forms that logback will pick up correctly. If may be necessary or desired to manually set the required parameters. A table follows of java (-D) properties that can be set to determine behavior.
Name |
Default |
Description |
|---|---|---|
logback.configurationFile |
$DCSTOOL_HOME/logback.xml $DCSTOOL_USERDIR/logback.xml if present |
Total control of the log back configuration The values below assume the processing present in the default config and may not have any affect if using your own |
LOG_DIR |
$DCSTOOL_USERDIR/logs |
Directory to which logs are stored if -l or $LOG_FILE are not used |
APP_NAME |
java class or value of -a command line option |
Base name of the log file and value for logback’s ContextName |
LOG_FILE |
${LOG_DIR/${APP_NAME}.log |
The file name of the log. Will be used as-is if set. |
LOG_LEVEL |
INFO |
Logging level to use. One of: (TRACE, DEBUG, INFO, WARN, ERROR, OFF) |
Warning
OpenDCS previously had 3 levels of debug. With the migration to slf4j there are only 2 levels, debug and trace. When using the numeric -dN command line option 2 and 3 are mapped to trace.
decj
The script decj (and decj.bat) are used to setup the environment and parameters before starting java. If LOGBACK_OVERRIDE is set any calculated values are set aside and only the parameters provided are used.
NOTE: at the time of writing, decj.bat may not have been updated to process any of the logback options. In that case manually set the above values to what is required.
Examples
Customization
If you want the overall behavior of the default logging, but want to change something like the maximum days or size of logs we recommend copying the logback.xml file from $DCSTOOL_HOME to $DCSTOOL_USERDIR and making the adjustments.
Docker
THe Docker containers use a default logback.xml that outputs JSONL event data. Control log level and context name with APP_NAME and LOG_LEVEL directly.
Choosing a different logger
If logback is not suitable for your usage, there are several logging providers that work with slf4j. While actual configuration of those providers is beyond the scope of this projects we are making use of the MappedDiagnosticContext and will likely make use of Markers. To get the most out of logging, your chosen logging provider should understand and be able to use these features.