|
| 1 | +--- |
| 2 | +title: "Logging" |
| 3 | +date: 2022-02-04T17:18:00-05:00 |
| 4 | +draft: false |
| 5 | +weight: 4 |
| 6 | +--- |
| 7 | + |
| 8 | +The WebLogic Deploy Tooling has a built-in logging framework based on `java.util.logging`. Its logging configuration |
| 9 | +is specified in `$WDT_HOME/etc/logging.properties`. By default, the logging framework writes to both the console and |
| 10 | +a log file. |
| 11 | + |
| 12 | +#### Log file |
| 13 | +By default, WDT tools write their log files to the `$WDT_HOME/logs` directory and the log file name reflects the name of the tool. |
| 14 | +For example, if you run the `validateModel` tool then the log file will be `$WDT_HOME/logs/validateModel.log`. These |
| 15 | +log files are overwritten each time you run a particular tool so the file contains only the logs from the last tool |
| 16 | +invocation. |
| 17 | + |
| 18 | +If the `$WDT_HOME/logs` directory is not writable by the user running the tool, the logging framework will search for |
| 19 | +a location to write the logs. The user must have write permission on the directory in order for it to be selected. |
| 20 | +The search order is as follows: |
| 21 | + |
| 22 | +- Check the `WLSDEPLOY_LOG_DIRECTORY` environment variable. |
| 23 | +- Check the current working directory (as defined by the `user.dir` Java system property) and create a `logs` subdirectory. |
| 24 | +- Check the temp directory (as defined by the `java.io.tmpdir` Java system property) and create a `wdt-logs` subdirectory. |
| 25 | + |
| 26 | +If none of these locations are writable, the logging framework prints an error message to `stderr` and exits. |
| 27 | + |
| 28 | +#### Console output |
| 29 | +WDT tools output logging information to `stdout` and `stderr`, as appropriate. By default, only `INFO` level messages |
| 30 | +are sent to `stdout`. All `WARNING` and `SEVERE` messages are set to `stderr`. In addition to regular log messages |
| 31 | +generated as the tool runs, the tools will produce a summary at the end of tool execution that gives the user an |
| 32 | +overview of the tool execution status. For example, the `validateModel` tool execution with no warnings or errors will |
| 33 | +produce output that looks similar to this: |
| 34 | + |
| 35 | +``` |
| 36 | +Issue Log for validateModel version 2.0.0 running WebLogic version 12.2.1.4.0.210930 offline mode: |
| 37 | +
|
| 38 | +Total: WARNING : 0 SEVERE : 0 |
| 39 | +``` |
| 40 | + |
| 41 | +#### Logging levels |
| 42 | +As mentioned previously, WDT's logging framework is based on `java.util.logging` so all logging levels defined in |
| 43 | +the `java.utiul.logging.Level` class apply to WDT loggers. For a quick review of those levels, see the |
| 44 | +[javadoc](https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html). |
| 45 | + |
| 46 | +WDT uses hierarchical loggers that align with the purpose of the code being executed. The root logger is named `wlsdeploy`. |
| 47 | +Many loggers exist underneath the root logger; for example, `wlsdeploy.create`, `wlsdeploy.discover`, and `wlsdeploy.util`. |
| 48 | +By default, the WDT `logging.properties` file sets the logging level of the root and several important loggers. If the |
| 49 | +level for a particular logger is not set, that logger will use the level of its parent logger. This delegation to the |
| 50 | +parent logger is recursive up the hierarchy until it finds a level to use. |
| 51 | + |
| 52 | +In WDT, the log file will collect log entries from all loggers based on the logger's `level` while the console output |
| 53 | +is limited to `INFO` and above only. Log entries written to the console will not display any exception stack traces |
| 54 | +associated with a log entry. To see those, you must look at the log file. The WDT logging framework supports using the |
| 55 | +`wlsdeploy.debugToStdout` Java system property to allow debug log messages (those logged at the `FINE` level or below) |
| 56 | +to appear in `stdout` as long as the loggers to which the messages are logged are not filtering those log levels. For |
| 57 | +example, doing the following will cause debug output to be written to the console: |
| 58 | + |
| 59 | +``` |
| 60 | +export WLSDEPLOY_PROPERTIES=-Dwlsdeploy.debugToStdout=true |
| 61 | +weblogic-deploy/bin/prepareModel.sh ... |
| 62 | +``` |
| 63 | + |
| 64 | +#### Log handlers |
| 65 | +WDT uses several log handlers to handle logging output of data to various sources. |
| 66 | + |
| 67 | + | Log Handler | Output Destination | Description | |
| 68 | + | ----------- |----------------------------------------------------------------------------------| ----------- | |
| 69 | + | `java.util.logging.FileHandler` | WDT tool log file | The standard `java.util.logging` file handler. | |
| 70 | + | `oracle.weblogic.deploy.logging.StdoutHandler` | `stdout` | WDT handler that writes `INFO` level messages to the console. | |
| 71 | + | `oracle.weblogic.deploy.logging.StderrHandler` | `stderr` | WDT handler that writes `WARNING` and `SEVERE` level messages to the console. | |
| 72 | + | `oracle.weblogic.deploy.tooling.SummaryHandler` | `stdout` | WDT handler that writes the tool's execution summary information to the console. | |
| 73 | + |
| 74 | +By default, all four handlers are used and configured appropriately. The logging framework intentionally limits the |
| 75 | +configurability of these handlers. Only the following `logging.properties` file settings are allowed. |
| 76 | + |
| 77 | + | Property | Value(s) Allowed | Behavior When Set | |
| 78 | + |----------------------------------|----------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------------------| |
| 79 | + | `handlers` | comma-separated list of handlers | The list of handlers to use (removing a handler from the list is the same as setting its `level` property to `OFF`). | |
| 80 | + | `java.util.logging.FileHandler.level` | `OFF` | No logging output will be saved in the log file. | |
| 81 | + | `oracle.weblogic.deploy.logging.StdoutHandler.level` | `OFF` | No `INFO` level logging output will be written to the console. | |
| 82 | + | `oracle.weblogic.deploy.logging.StderrHandler.level` | `OFF` | No `WARNING` or `ERROR` level logging output will be written to the console. | |
| 83 | + | `oracle.weblogic.deploy.logging.SummaryHandler.level` | `OFF` | No tool execution summary output will be written to the console. | |
| 84 | + | `oracle.weblogic.deploy.logging.SummaryHandler.size` | Any number | Limits the number of memory-buffered `WARNING` and `ERROR` log records (default is 3000). | |
| 85 | + |
| 86 | +Use the `WLSDEPLOY_LOG_HANDLERS` environment variable as an alternative to specifying the list of handlers in the |
| 87 | +`logging.properties` file's `handlers` property. |
| 88 | + |
| 89 | +Any attempts to set other configuration for these log handlers will simply be discarded by the WDT logging framework at startup. |
0 commit comments