C:\Oracle\Middleware\Oracle_Home\user_projects\applications\medrec\dist\standalone\exploded\medrec\META-INF\weblogic-diagnostics.xml 

You can deploy the diagnostic module in both exploded and unexploded archives.

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 about creating modules and deploying applications, see Deploying Applications to Oracle 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 15-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.

^Footnote 1

See Using Deployment Plans to Dynamically Control Instrumentation Configuration, for information about HotSwap.

WebLogic Server supports deployment plans, as specified in the Jakarta EE Deployment Specification API (JSR-88). With deployment plans, you can modify the configuration of an application after it 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 Oracle WebLogic Server.

If you want to reconfigure an application that was deployed without a deployment plan, you must undeploy, unarchive, reconfigure, re-archive, 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 Java HotSwap (see Enabling Java HotSwap) before deploying your application with a deployment plan, you can dynamically update all instrumentation settings without redeploying the application. If you do not enable HotSwap, or if you do not use a deployment plan, changes to some instrumentation settings require redeployment, as shown in Table 15-2.

^Footnote 2

If HotSwap 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>

You can use a deployment plan to dynamically control the configuration options of an application-scoped diagnostic module.

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

   Oracle recommends that you create an empty descriptor. This 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 be unable 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://xmlns.oracle.com/weblogic/weblogic-diagnostics/2.0/weblogic-diagnostics.xsd.

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 Java HotSwap. See Enabling Java HotSwap.
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.

The PlanGenerator tool inspects all Jakarta EE 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.

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

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

For more information about creating and using deployment plans, see Configuring Applications for Production Deployment in Deploying Applications to Oracle 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 Oracle WebLogic Server

You can create a simple deployment plan for diagnostics using PlanGenerator.

Example 15-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.

<?xml version='1.0' encoding='UTF-8'?>
<deployment-plan xmlns="http://xmlns.oracle.com/weblogic/weblogic-diagnostics"
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>

You can enable Java HotSwap to update the configuration of the application with the modified deployment plan values.

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

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 WebLogic Remote 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.

You can change configuration settings by modifying the deployment plan and then updating or redeploying the application, depending on whether HotSwap is enabled.

See Enabling Java HotSwap 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 WebLogic Remote Console or the WebLogic Scripting Tool (WLST).

If you enabled HotSwap, 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 HotSwap, 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')