This chapter describes how to apply debug patches dynamically, allowing you to capture diagnostic information using a patch that is activated and deactivated without requiring a server restart.
This chapter includes the following sections:
Debug patches, packaged as JAR files, are generated through My Oracle Support (https://support.oracle.com/) and used to gather additional information about an error when it occurs in a production environment. Typically, the debug patch JAR files are added to the classpath and all server instances must be restarted for the JAR files to take effect. This can present problems, as it might not be possible to restart the server instances in a production environment due to scheduling and other constraints. Additionally, after the server instances are restarted, in-memory states are lost and the problem may disappear or take awhile to reappear. Dynamic application of debug patches allows you to avoid these server restarts while applying instrumented debug patches to gather this additional information. Also, when these debug patches are no longer needed, they can be deactivated without server restarts.
When dynamically applying debug patches, WebLogic Server uses Java HotSwap to replace the loaded classes with the versions provided in the debug patch JAR files. For information on Java HotSwap, see Enabling Java HotSwap.
Debug patch JAR files are picked up from a specific directory called the debug patch directory. This directory is specified domain-wide using the DebugPatchDirectory attribute of the DebugPatchesMBean. By default, the debug_patches directory under the DOMAIN_HOME directory is used as the debug patch directory.
This feature is available to users with administrative privileges in the domain. Only authorized users are able to post debug patch JAR files in the debug patch directory. This directory must be properly protected with file system permissions.
In order to apply debug patches dynamically, the target WebLogic Server instances must be started on the command line with the WLDF debug patch agent. The WLDF debug patch agent handles the following:
Replaces the loaded classes with the instrumented classes from the debug patch JAR.
Makes sure that the replacement classes in the debug patch JAR have the same shape as the original classes. If any of the classes do not meet this requirement, none of the classes in the debug patch JAR are swapped in and an error message is logged.
Logs informational messages to indicate the start and completion of debug patch activation or deactivation.
Allows only properly authenticated users with administrative privileges to apply a debug patch.
To specify the WLDF debug patch agent on the command line, update your startup script to include the following:
-javaagent:$WL_HOME/server/lib/debugpatch-agent.jar
Note:
New startup scripts will automatically include thedebug-agent.jar on the command line unless the disableDebugPatches option is specified on the startup script command line.The WLST commands summarized in Table 18-1 allow you to list, activate, and deactivate dynamic debug patches.
Table 18-1 WLST Commands Used With Debug Patches
| Command | Summary |
|---|---|
activateDebugPatch |
Activates a debug patch on the specified targets. |
deactivateAllDebugPatches |
Deactivates all debug patches on the specified targets. |
deactivateDebugPatches |
Deactivates a debug patch on the specified targets. |
listDebugPatches |
Lists the active and available debug patches on the specified targets. |
listDebugPatchTasks |
Lists the debug patch (activated or deactivated) tasks from the specified targets. |
purgeDebugPatchTasks |
Purges the debug patch (activated or deactivated) tasks on the specified targets. |
showDebugPatchInfo |
Displays details about a debug patch on the specified targets. |
Example 18-1, Example 18-2, and Example 18-3 demonstrate how to use the activateDebugPatch command to activate a debug patch on the desired targets. Note that if a specified debug patch is not available in the debug patch directory on a target, a warning is issued and WebLogic Server will attempt to proceed and activate the debug patch on the remaining targets. If one of the classes in the debug patch fails to replace the original class on a target, the entire debug patch JAR file is rejected on that target and WebLogic Server will attempt to activate the debug patch on the remaining targets. Additionally, several debug patches may be activated over time and each debug patch will overlay the original classes and previously activated debug patches. If a class is contained in multiple activated debug patches, the class in the debug patch that was last activated has precedence. The activateDebugPatch command returns an array of tasks, each element corresponding to the activation activity on an affected target server instance.
Example 18-1 Activating a Debug Patch on Two Managed Servers
# Connected to admin server: Activate debug-patch-01.jar on managed servers # MS1 and MS2 tasks=activateDebugPatch(Patch='debug-patch-01.jar', Target='MS1,MS2')
Example 18-4, Example 18-5, and Example 18-6 demonstrate how to use the deactivateDebugPatches command to deactivate debug patches. To specify more than one debug patch, use a comma-separated list. If a specified debug patch is not active on a target, a warning is issued and the command continues. If no debug patches are specified, all active patches are deactivated on the specified targets and the original classes are activated. After successful deactivation, all targets are left in the same state they were in prior to running this command. The deactivateDebugPatches command returns an array of tasks.
Example 18-4 Deactivating Debug Patches on a Managed Server
# Connected to MS1: deactivate debug-patch-01.jar tasks=deactivateDebugPatches(Patches='debug-patch-01.jar')