18 Using Debug Patches
The WebLogic Diagnostics Framework (WLDF) supports the ability for you to apply debug patches dynamically, allowing you to capture diagnostic information using a patch that you can activate and deactivate without the need of a server restart.
- Dynamic Application of Debug Patches
Dynamic application of debug patches allows you to avoid the server restarts while applying instrumented debug patches to gather additional information about an error. - Specifying the Debug Patch Directory
Debug patch JAR files are picked up from a specific directory called the debug patch directory. - Configuring the WLDF Debug Patch Agent
To apply debug patches dynamically, the target WebLogic Server instances must be started on the command line with the WLDF debug patch agent. - WLST Commands for Debug Patches
WLDF provides a set of WLST commands you can use to list, activate, and deactivate dynamic debug patches.
Dynamic Application of Debug Patches
Dynamic application of debug patches allows you to avoid the server restarts while applying instrumented debug patches to gather additional information about an error.
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. 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. See Enabling Java HotSwap.
Parent topic: Using Debug Patches
Specifying the Debug Patch Directory
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.
Parent topic: Using Debug Patches
Configuring the WLDF Debug Patch Agent
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 the debug-agent.jar
on the command line unless the disableDebugPatches
option is specified on the startup script command line.
Parent topic: Using Debug Patches
WLST Commands for Debug Patches
WLDF provides a set of WLST commands you can use to list, activate, and deactivate dynamic debug patches.
Table 18-1 summarizes the list of WLST commands used with 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. |
Parent topic: Using Debug Patches
Dynamically Activating a Debug Patch
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-2 Activating a Debug Patch on a Server Instance and a Cluster
# Connected to admin server: Activate debug-patch-01.jar on myserver and all # members of cluster Cluster-0 tasks=activateDebugPatch(Patch='debug-patch-01.jar', Target='myserver,Cluster-0')
Example 18-3 Activating a Debug Patch on an Application Targeted to a Cluster
# Connected to admin server: Activate debug-patch-03.jar on application 'medrec' # targeted to cluster Cluster-1 tasks=activateDebugPatch(Patch='debug-patch-03.jar', Target='Cluster-1', Application='medrec')
Parent topic: WLST Commands for Debug Patches
Dynamically Deactivating Debug Patches
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')
Example 18-5 Deactivating Debug Patches on All Members of a Cluster
# Connected to admin server: de-activate debug-patch-01.jar # and debug-patch-02.jar on all members of cluster Cluster-0 tasks=deactivateDebugPatches(Patches='debug-patch-01.jar,debug-patch-02.jar', Target='Cluster-0')
Example 18-6 Deactivating Debug Patches on an Application Targeted to a Cluster
# Connected to admin server: de-activate debug-patch-03.jar on application # 'medrec' targeted to cluster Cluster-1 tasks=deactivateDebugPatches(Patches='debug-patch-03.jar', Target='Cluster-1', Application='medrec')
Parent topic: WLST Commands for Debug Patches