20 Using the WebLogic Server Diagnostic Framework (WLDF)

This chapter describes the integration of Oracle Communications Converged Application Server with the WebLogic Diagnostic Framework (WLDF).

Overview of Converged Application Server and the WLDF

The WebLogic Diagnostic Framework (WLDF) consists of a number of components that work together to collect, archive, and access diagnostic information about a WebLogic Server instance and its applications. Converged Application Server version integrates with several components of the WLDF in order to monitor and diagnose the operation of engines, as well as deployed SIP Servlets:

Data Collectors: Converged Application Server integrates with the Harvester service to collect information from runtime MBeans, and with the Logger service to archive SIP requests and responses.
Watches and Notifications: Administrators can use the Watches and Notifications component to create complex rules, based on Converged Application Server runtime MBean attributes, that trigger automatic notifications using JMS, JMX, SNMP, SMTP, and so forth.
Image Capture: Converged Application Server instances can collect certain diagnostic data and write the data to an image file when requested by an Administrator. This data can then be used to diagnose problems in a running server.
Instrumentation: Converged Application Server instruments the server and application code with monitors to help you configure diagnostic actions that are performed on SIP messages (requests and responses) that match certain criteria.

The sections that follow provide more details about how Converged Application Server integrates with each of the above WLDF components. See "Introduction and Roadmap" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server for more information about WLDF.

Data Collection and Logging

Converged Application Server uses the WLDF Harvester service to collect data from the attributes of these runtime MBeans:

SipApplicationRuntimeMBean
SipServerRuntimeMBean

You can add charts and graphs of this data to your own custom views using the WLDF console extension. To do so, first enable the WLDF console extension by copying the JAR file into the console-ext subdirectory of your domain directory:

cp ~/ORACLE_HOME/Middleware/Oracle_Home/wlserver/server/lib/console-ext/diagnostics-console-extension.jar ~/ORACLE_HOME/Middleware/Oracle_Home/user_projects/domains/base_domain/console-ext

When accessing the WLDF console extension, the Converged Application Server runtime MBean attributes are available in the Metrics tab of the extension.

Converged Application Server also uses the WLDF Logger service to archive SIP and Diameter messages to independent, dedicated log files (by default, domain_home/logs/server_name/sipMessages.log). You can configure the name and location of the log file, as well as log rotation policies, using the Configuration > Message Debug tab in the SIP Server Administration Console extension. See "Enabling Message Logging" in Converged Application Server Developer's Guide. Note that a server restart is necessary in order to initiate independent logging and log rotation.

Watches and Notifications

The data collected from Converged Application Server runtime MBeans can be used to create automated monitors, or "watches," that observe a server's diagnostic state. One or more notifications can then be configured for use by a watch, in order to generate a message using SMTP, SNMP, JMX, or JMS when your configured watch conditions and rules occur.

To use watches and notifications, you select the Diagnostics > Diagnostic Modules node in the left pane of the Administration Console and create a new module with the watch rules and notifications required for monitoring your servers. The watch rules can use the metrics collected from Converged Application Server runtime MBeans, messages written to the log file, or events generated by the diagnostic framework.

Image Capture

Converged Application Server adds its own image capture information to the diagnostic image generated by the WLDF. You can generate diagnostic images either on demand, or automatically by configuring watch rules.

The information contained in diagnostic images is intended for use by Oracle technical support personnel when troubleshooting a potential server problem and includes:

Call state and timer statistics.
Work manager statistics.

Instrumentation

The WLDF instrumentation system creates diagnostic monitors and inserts them into Converged Application Server or application code at specific points in the flow of execution. Converged Application Server integrates with the instrumentation service to provide a built-in DyeInjection monitor. When enabled, this monitor injects dye flags into the diagnostic context when certain SIP messages enter or exist the system. Dye flags are injected based on the monitor's configuration properties, and on certain request attributes.

Converged Application Server adds the dye flags described in Table 20-1 below, as well as the WebLogic Server dye flags USER and ADDR. See "Configuring the DyeInjection Monitor to Manage Diagnostic Contexts" in Oracle Fusion Middleware Configuring and Using the Diagnostics Framework for Oracle WebLogic Server for more information.

Table 20-1 Converged Application Server DyeInjection Flags

Dye Flag	Description
PROTOCOL_SIP	Set in the diagnostic context of all SIP protocol messages.
SIP_REQ	Set in the diagnostic context for all SIP requests that match the value of the property SIP_REQ.
SIP_RES	Set in the diagnostic context for all SIP responses that match the value of the property SIP_RES.
SIP_REQURI	Set if a SIP request's request URI matches the value of property SIP_REQURI.
SIP_ANY_HEADER	Set if a SIP request contains a header matching the value of the property SIP_ANY_HEADER. The value of SIP_ANY_HEADER is specified using the format `messageType.headerName=headerValue` where `headerValue` is either a value or regular expression. For example, you can specify the property as SIP_ANY_HEADER=request.Contact=sip:sipp@localhost:5061 or SIP_ANY_HEADER=response.Contact=sip:findme@172.17.30.50:5060.

Dye flags can be applied to both incoming and outbound SIP messages. The flags are useful for dye filtering, and can be used by delegating monitors to trigger further diagnostic actions.

Converged Application Server provides several delegating monitors that can be applied at the application and server scope, and which may examine dye flags set by the DyeInjection monitor. The delegating monitors are described in Table 20-2.

Table 20-2 Converged Application Server Diagnostic Monitors

Monitor Name	Monitor Type	Scope	Pointcuts
occas/Sip_Servlet_Before_Service	Before	Application	At entry of `SipServlet.do*` or `SipServlet.service` methods of all implementing subclasses.
occas/Sip_Servlet_After_Service	After	Application	At exit of `SipServlet.do*` or `SipServlet.service` methods of all implementing subclasses.
occas/Sip_Servlet_Around_Service	Around	Application	At entry and exit of `SipServlet.do*` or `SipServlet.service` methods of all implementing subclasses.
occas/Sip_Servlet_Before_Session	Before	Application	At entry of `getAttribute`, `set`, `remove`, and `invalidate` methods for both `SipSession` and `SipApplicationSession`.
occas/Sip_Servlet_After_Session	After	Application	At exit of `getAttribute`, `set`, `remove`, and `invalidate` methods for both `SipSession` and `SipApplicationSession`.
occas/Sip_Servlet_Around_Session	Around	Application	At entry and exit of `getAttribute`, `set`, `remove`, and `invalidate` methods for both `SipSession` and `SipApplicationSession`.
occas/SipSessionDebug	Around	Application	This is a built-in, application-scoped monitor having fixed pointcuts and a fixed debug action. Before and after a pointcut, the monitor performs the `SipSessionDebug` diagnostic action, which calculates the size of the SIP session after serializing the underlying object. The pointcuts for this monitor are as follows: Before and after calls to `getSession` and `getApplicationSession` of the `SipServletMessage` class hierarchy. Before and after calls to `getAttribute`, `setAttribute`, and `removeAttribute` methods in the `SipSession` and `SipApplicationSession` classes. Note: The `occas/SessionDebugAction-Before` event is not triggered for the `req.getSession()` or `req.getApplicationSession()` joinpoints. Only the `occas/SessionDebugAction-After` is triggered, because the Session is made available for inspection only after the joinpoints have executed. Note: If you compile your application using Apache Ant, you must enable the `debug` attribute to embed necessary debug information into the generated class files.
occas/Sip_Servlet_Before_Message_Send_Internal	Before	Server	At entry of Converged Application Server code that writes messages to the wire.
occas/Sip_Servlet_After_Message_Send_Internal	After	Server	At exit of Converged Application Server code that writes messages to the wire.
occas/Sip_Servlet_Around_Message_Send_Internal	Around	Server	At entry and exit of Converged Application Server code that writes messages to the wire.

Configuring Server-Scoped Monitors

To use the server-scoped monitors, you must create a new diagnostic module and create and configure one or more monitors in the module. For the built-in DyeInjection monitor, you then add monitor properties to define the specific dye flags. For delegating monitors such as occas/Sip_Servlet_Before_Message_Send_Internal, you add monitor properties to define diagnostic actions.

Follow these steps to configure the Converged Application Server DyeInjection monitor, a delegate monitor, and enable dye filtering:

Access the Administration Console for you domain.
If your domain is running in Production mode, click Lock & Edit.
Select Diagnostics, then select the Diagnostic Modules node in the left pane of the console.
Click New to create a new Diagnostic Module. Give the module a descriptive name, such as "instrumentationModule," and click OK.
Select the new "instrumentationModule" from the list of modules in the table.
Select the Targets tab.
Select a server on which to target the module and click Save.
Return to the Diagnostic Modules node and select instrumentationModule from the list of modules.
Select Configuration, then select the Instrumentation tab.
Select Enabled to enable instrumentation at the server level, then click Save.
Add the DyeInjection monitor to the module:
1. Click Add/Remove.
2. Select the name of a monitor from the Available list (for example, DyeInjection), and use the arrows to move it to the Chosen list.
3. Click OK.
4. Select the newly-created monitor from the list of available monitors.
5. Ensure that the monitor is enabled, and edit the Properties field to add any required properties. For the DyeInjection monitor, sample properties include:
```
SIP_RES=180
SIP_REQ=INVITE
SIP_ANY_HEADER=request.Contact=sip:sipp@localhost:5061
```
6. Click Save.
Add one or more delegate monitors to the module:
1. Return to the Configuration > Instrumentation tab for the new module.
2. Click Add/Remove.
3. Select the name of a delegate monitor from the Available list (for example, occas/Sip_Servlet_Before_Message_Send_Internal), and use the arrows to move it to the Chosen list.
4. Click OK.
5. Select the newly-created monitor from the list of available monitors.
6. Ensure that the monitor is enabled, then select one or more Actions from the available list, and use the arrows to move the actions to the Chosen list. For the occas/Sip_Servlet_Before_Message_Send_Internal monitor, sample actions include DisplayArgumentsAction, StackDumpAction, ThreadDumpAction, and TraceAction.
7. Select the check box to EnableDyeFiltering.
8. Select one or more Dye Masks, such as SIP_REQ, from the Available list and use the arrows to move them to the Chosen list.
9. Click Save.
  
  Note:
  You can repeat the above steps to create additional delegate monitors.
If your domain is running in Production mode, click Activate Changes.

Configuring Application-Scoped Monitors

You configure application-scoped monitors in an XML configuration file named weblogic-diagnostics.xml. You must store the weblogic-diagnostics.xml file in the SIP module's or enterprise application's META-INF directory.

The XML file enables instrumentation at the application level, defines point cuts, and also defines delegate monitor dye masks and actions. Example 20-1 shows a sample configuration file that uses the occas/Sip_Servlet_Before_Service monitor.

Example 20-1 Sample weblogic-diagnostics.xml File

<wldf-resource xmlns="http://www.bea.com/ns/weblogic/90/diagnostics">
  <instrumentation>
    <enabled>true</enabled>
    <include>demo.ProxyServlet</include>
    <wldf-instrumentation-monitor>
      <name>occas/Sip_Servlet_Before_Service</name>
      <enabled>true</enabled>
      <dye-mask>SIP_ANY_HEADER</dye-mask>
      <dye-filtering-enabled>true</dye-filtering-enabled>
      <action>DisplayArgumentsAction</action>
    </wldf-instrumentation-monitor>  
   </instrumentation>
</wldf-resource>

In this example, if an incoming request's diagnostic context contains the SIP_ANY_HEADER dye flag, then the occas/Sip_Servlet_Before_Service monitor is triggered and the DisplayArgumentsAction is executed.

See "Configuring Instrumentation" in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server for more information about creating the weblogic-diagnostics.xml configuration file.