Skip navigation.
Downloads | Product Documentation | Support

Configuring and Using the WebLogic Diagnostics Framework

# Deploying WLDF Application Modules

The only WebLogic Diagnostic Framework (WLDF) component you can use with applications is Instrumentation. See Configuring Application-Scoped Instrumentation.

You configure and manage instrumentation for an application as a diagnostics application module, which is an application-scoped resource. The configuration is persisted in a descriptor file which you deploy with the application. A diagnostic module deployed in this way is available only to the enclosing application. Using application-scoped resources ensures that an application always has access to required resources and simplifies the process of deploying the application to new environments.

You can deploy an application using a deployment plan, which permits dynamic configuration updates.

Note: For instrumentation to be available for an application, instrumentation must be enabled on the server to which the application is deployed. (Server-scoped instrumentation is enabled and disabled in the `<instrumentation>` element of the diagnostics descriptor for the server.)

The following sections describe how to deploy WLDF application modules:

- Deploying a Diagnostic Module as an Application-Scoped Resource
- Using Deployment Plans for Dynamically Controlling Instrumentation Configuration
- Using a Deployment Plan: Overview
- Creating a Deployment Plan Using weblogic.PlanGenerator
- Sample Deployment Plan for Diagnostics
- Enabling Hot-Swap Capabilities
- Deploying an Application with a Deployment Plan
- Updating an Application with a Modified Plan

# Deploying a Diagnostic Module as an Application-Scoped Resource

To deploy a diagnostic module as an application-scoped resource, you configure the module in a descriptor file named `weblogic-diagnostics.xml`. Then you package the descriptor file with the application archive in the `ARCHIVE_PATH``/META-INF` directory for the deployed application (for example,`D:\bea\weblogic91\samples\server\medrec\medrecEar
\META-INF\weblogic-diagnostics.xml`). You can deploy the diagnostic module in both exploded and unexploded archives.

Note: If the EAR archive contains WAR, RAR or EJB modules that have the `weblogic-diagnostics.xml` descriptors in their `META-INF` directory, those descriptors are ignored.

You can use any of the standard WebLogic Server tools provided for controlling deployment, including the WebLogic Administrative Console or the WebLogic Scripting Tool (WLST).

For information on creating modules and deploying applications, see Deploying Applications to WebLogic Server.

Because of the different ways that diagnostic application modules and diagnostic system modules are deployed, there are some differences in how you can reconfigure them and when those changes take place, as shown in Table 13-1. The details of how to work with diagnostic application modules is described throughout this section. See Configuring Instrumentation, for information about working with diagnostic system modules.

Table 13-1 Comparing System and Application Modules

Module Type | Add/Remove Objects Dynamically | Add/Remove Objects with Console | Modify with JMX Remotely | Modify with JSR-88 (non-remote) | Modify with Console
System Module | Yes | Yes | Yes | No | Yes - via JMX
Application Module | Yes, when hot swap1 is enabled No, when hot swap is not enabled: module must be redeployed | Yes | No | Yes | Yes - via plan

1. See Using Deployment Plans for Dynamically Controlling Instrumentation Configuration, for information about hot swap.

# Using Deployment Plans for Dynamically Controlling Instrumentation Configuration

WebLogic Server supports deployment plans, as specified in the J2EE Deployment Specification API (JSR-88). With deployment plans, you can modify an application's configuration after the application is built, without having to modify the application archives. For complete documentation on using deployment plans in WebLogic Server, see Configuring Applications for Production Deployment in Deploying Applications to WebLogic Server.

If you want to reconfigure an application that was deployed without a deployment plan, you must undeploy, unarchive, reconfigure, rearchive, and then redeploy the application. With a configuration plan, you can dynamically change many configuration options simply by updating the plan, without modifying the application archive.

If you enable a feature called "hot swap" (see Enabling Hot-Swap Capabilities) before deploying your application with a deployment plan, you can dynamically update all instrumentation settings, without redeploying the application. If you do not enable hot swap, or if you do not use a deployment plan, changes to some instrumentation settings require redeployment, as shown in Table 13-2.

Table 13-2 When Application Instrumentation Configuration Changes Take Effect

| Add and remove monitors | Attach and detach actions | Enable and disable monitors
Application deployed with a deployment plan, hot swap enabled | Dynamic | Dynamic | Dynamic
Application deployed with a deployment plan, hot swap not enabled | Must redeploy application1 | Dynamic | Dynamic
Application deployed without a deployment plan | Must redeploy application | Must redeploy application | Must redeploy application

1. If hot-swap is not enabled, you can "remove" a monitor, but that just disables it. The instrumentation code is still woven into the application code. You cannot re-enable it through a modified plan.

You can use a deployment plan to dynamically update configuration elements without redeploying the application.

- <enabled>
- <dye-filtering-enabled>
- <dye-mask>
- <action>

# Using a Deployment Plan: Overview

The general process for creating and using a deployment plan is as follows:

1. Create a well-formed `weblogic-diagnostics.xml` descriptor file for the application.

It is recommended that you create an empty descriptor. That provides full flexibility for dynamically modifying the configuration. It is possible to create monitors in the original descriptor file and then use a deployment plan to override the settings. However, you will not be able to completely remove monitors without redeploying. If you add monitors using a deployment plan to an empty descriptor, all such monitors can be removed. For information about configuring diagnostic application modules, see Configuring Application-Scoped Instrumentation.

The schema for `weblogic-diagnostics.xml` is available at `http://www.bea.com/ns/weblogic/90/diagnostics.xsd`. See WebLogic Server Diagnostics Configuration Schema Reference for documentation.

2. Place the descriptor file `weblogic-diagnostics.xml`, in the top-level `META-INF` directory of the appropriate archive.
3. Create a deployment plan, for example by using weblogic.PlanGenerator. See Creating a Deployment Plan Using weblogic.PlanGenerator.
4. Start the server, optionally enabling "hot-swap" capability. See Enabling Hot-Swap Capabilities.
5. Deploy the application using the deployment plan. See Deploying an Application with a Deployment Plan).
6. When needed, edit the plan and update the application with the plan. See Updating an Application with a Modified Plan.

# Creating a Deployment Plan Using weblogic.PlanGenerator

You can use the `weblogic.PlanGenerator` tool to create an initial deployment plan, and interactively override specific properties of the `weblogic-diagnostics.xml` descriptor.

The `PlanGenerator` tool inspects all J2EE deployment descriptors in the selected application, and creates a deployment plan with null variables for all relevant WebLogic Server deployment properties that configure external resources for the application.

To create the plan, use the following syntax:

`java weblogic.PlanGenerator -plan output-plan.xml [options]
application-path`

For example:

`java weblogic.PlanGenerator -plan foo.plan -dynamics /test/apps/mywar`

Note: The `-dynamics` options specifies that the plan should be generated to include only those options that can be dynamically updated.

For more information about creating and using deployment plans, see Configuring Applications for Production Deployment in Deploying Applications to WebLogic Server.

For more information about using `PlanGenerator`, see weblogic.PlanGenerator Command Line Reference and Exporting an Application for Deployment to New Environments in Deploying Applications to WebLogic Server.

# Sample Deployment Plan for Diagnostics

Listing 13-1 shows a simple deployment plan generated using `weblogic.PlanGenerator`. (For readability, some information has been removed.) The plan enables the `Servlet_Before_Service` monitor and attaches to it the actions `DisplayArgumentsAction` and `StackDumpAction`.

Listing 13-1 Sample Deployment Plan

>     <?xml version='1.0' encoding='UTF-8'?>

>     <deployment-plan xmlns="http://www.bea.com/ns/weblogic/90"
>     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>     global-variables="false">
>       <application-name>jsp_expr_root</application-name>

>       <variable-definition>
>         <!-- Add two additional actions to Servlet_Before_Service monitor -->
>         <variable>
>           <name>WLDFInstrumentationMonitor_Servlet_Before_Service_Actions_113050559713922</name>
>           <value>"DisplayArgumentsAction","StackDumpAction"</value>
>         </variable>
>         <-- Enable the Servlet_Before_Service monitor -->
>         <variable>
>           <name>WLDFInstrumentationMonitor_Servlet_Before_Service_Enabled_113050559713927</name>
>           <value>true</value>
>         </variable>
>       </variable-definition>

>       <module-override>
>         <module-name>jspExpressionWar</module-name>
>         <module-type>war</module-type>
>         <module-descriptor external="false">
>           <root-element>weblogic-web-app</root-element>
>           <uri>WEB-INF/weblogic.xml</uri>
>         </module-descriptor>
>         <module-descriptor external="false">
>         <root-element>web-app</root-element>
>         <uri>WEB-INF/web.xml</uri>
>         </module-descriptor>
>         <module-descriptor external="false">
>           <root-element>wldf-resource</root-element>
>           <uri>META-INF/weblogic-diagnostics.xml</uri>
>           <variable-assignment>
>             <name>WLDFInstrumentationMonitor_Servlet_Before_Service_Actions_113050559713922</name>
>             <xpath>/wldf-resource/instrumentation/wldf-instrumentation-monitor/[name="Servlet_Before_Service"]/action</xpath>
>             </variable-assignment>
>             <variable-assignment>
>               <name>WLDFInstrumentationMonitor_Servlet_Before_Service_Enabled_113050559713927</name>
>               <xpath>/wldf-resource/instrumentation/wldf-instrumentation-monitor/[name="Servlet_Before_Service"]/enabled</xpath>
>             </variable-assignment>
>           </module-descriptor>
>         </module-override>
>       <config-root xsi:nil="true"></config-root>
>     </deployment-plan>

For a list and documentation of diagnostic monitors and actions that you can specify in the deployment plan, see WLDF Instrumentation Library.

# Enabling Hot-Swap Capabilities

To enable hot-swap capabilities, start the server with the following command line switch:

`-javaagent:$WL_HOME/server/lib/diagnostics-agent.jar`

# Deploying an Application with a Deployment Plan

To take advantage of the dynamic control provided by a deployment plan, you must deploy the application with the plan.

You can use any of the standard WebLogic Server tools for controlling deployment, including the Administration Console or the WebLogic Scripting Tool (WLST). For example, the following WLST command deploys an application with a corresponding deployment plan.

>         wls:/mydomain/serverConfig> deploy('myApp', './myApp.ear', 'myserver',
>               'nostage', './plan.xml')

After deployment, the effective diagnostic monitor configuration is a combination of the original descriptor, combined with the overridden attribute values from the plan. If the original descriptor did not include a monitor with the given name and the plan overrides an attribute of such a monitor, the monitor is added to the set of monitors to be used with the application. This way, if your application is built with an empty `weblogic-diagnostics.xml` descriptor, you can add diagnostic monitors to the application during or after the deployment process, without having to modify the application archive.

# Updating an Application with a Modified Plan

You change configuration settings by modifying the deployment plan and then updating or redeploying the application, depending on whether or not hot swap is enabled. (See Table 13-2 to see when you can simply update the application and when you must redeploy it.) You can use any of the standard WebLogic Server tools for updating or redeploying, including the Administration Console or the WebLogic Scripting Tool (WLST).

If you enabled hot-swap, you can update the configuration for the application with the modified plan values by updating the application with the plan. For example, the following WLST command updates an application with a plan:

`wls:`/mydomain/serverConfig`> updateApplication('BigApp',
'c:/myapps/BigApp/newPlan/plan.xml', stageMode='STAGE',
testMode='false')`

If you did not enable hot-swap, you must redeploy the application for certain changes to take effect. For example, the following WLST command redeploys an application using a plan:

`wls:/mydomain/serverConfig> redeploy('myApp' 'c:/myapps/plan.xml')`