Using the WebLogic Server Diagnostic Framework (WLDF)

The following sections describe how WebLogic SIP Server is integrated with the WebLogic Diagnostic Framework (WLDF):

Overview of WebLogic SIP 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. WebLogic SIP Server version 3.1 integrates with several components of the WLDF in order to monitor and diagnose the operation of engine and data tier nodes, as well as deployed SIP Servlets:

Data Collectors—WebLogic SIP 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 WebLogic SIP Server runtime MBean attributes, that trigger automatic notifications using JMS, JMX, SNMP, SMTP, and so forth.
Image Capture—WebLogic SIP 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—WebLogic SIP 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 WebLogic SIP Server integrates with each of the above WLDF components. See Configuring and Using the WebLogic Diagnostics Framework in the WebLogic Server 9.2 documentation for more information about how the WLDF works, and how to configure different WLDF components. See also Using the WebLogic Diagnostic Framework Console Extension in the WebLogic Server 9.2 documentation for information about using the WLDF console extension to collect and monitor diagnostic information.

Data Collection and Logging

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

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:

When accessing the WLDF console extension, the WebLogic SIP Server runtime MBean attributes are available in the Metrics tab of the extension. See Using the WebLogic Diagnostic Framework Console Extension in the WebLogic Server 9.2 documentation for more information.

WebLogic SIP Server also uses the WLDF Logger service to archive SIP and Diameter messages to independent, dedicated log files. In previous releases, log information was written to a common log file, along with general WebLogic Server log messages. WebLogic SIP Server 3.1 now logs messages to a dedicated log file (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 Developing Applications with WebLogic SIP Server. Note that a server restart is necessary in order to initiate independent logging and log rotation.

Watches and Notifications

The data collected from WebLogic SIP 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 WebLogic SIP Server runtime MBeans, messages written to the log file, or events generated by the diagnostic framework. See Configure watches and notifications in the WebLogic SIP Server 9.2 Administration Console Help for more information.

Image Capture

WebLogic SIP Server 3.1 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 BEA technical support personnel when troubleshooting a potential server problem and includes:

Instrumentation

The WLDF instrumentation system creates diagnostic monitors and inserts them into WebLogic SIP Server or application code at specific points in the flow of execution. WebLogic SIP 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.

WebLogic SIP Server adds the dye flags described in Table 3-1 below, as well as the WebLogic Server dye flags USER and ADDR. The available WebLogic Server dye flags are described in Dyes Supported by the DyeInjection Monitor in the WebLogic Server 9.2 documentation.

Table 3-1 WebLogic SIP Server DyeInjection Flags
Dye Flag	Description
PROTOCOL_SIP	This flag is set in the diagnostic context of all SIP protocol messages.
SIP_REQ	This flag is set in the diagnostic context for all SIP requests that match the value of the property SIP_REQ.
SIP_RES	This flag is set in the diagnostic context for all SIP responses that match the value of the property SIP_RES.
SIP_REQURI	This flag is set if a SIP request's request URI matches the value of property SIP_REQURI.
SIP_ANY_HEADER	This flag is 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. See Configuring the DyeInjection Monitor to Manage Diagnostic Contexts in the WebLogic Server 9.2 documentation for information about configuring the monitor.

WebLogic SIP 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 3-2.

Table 3-2 WebLogic SIP Server Diagnostic Monitors
Monitor Name	Monitor Type	Scope	Pointcuts
Sip_Servlet_Before_Service	Before	Application	At entry of `SipServlet.do*` or `SipServlet.service` methods of all implementing subclasses.
Sip_Servlet_After_Service	After	Application	At exit of `SipServlet.do*` or `SipServlet.service` methods of all implementing subclasses.
Sip_Servlet_Around_Service	Around	Application	At entry and exit of `SipServlet.do*` or `SipServlet.service` methods of all implementing subclasses.
Sip_Servlet_Before_Session	Before	Application	At entry of `getAttribute`, `set`, `remove`, and `invalidate` methods for both `SipSession` and `SipApplicationSession`.
Sip_Servlet_After_Session	After	Application	At exit of `getAttribute`, `set`, `remove`, and `invalidate` methods for both `SipSession` and `SipApplicationSession`.
Sip_Servlet_Around_Session	Around	Application	At entry and exit of `getAttribute`, `set`, `remove`, and `invalidate` methods for both `SipSession` and `SipApplicationSession`.
Sip_Servlet_Before_Message_Send_Internal	Before	Server	At entry of WebLogic SIP Server code that writes messages to the wire.
Sip_Servlet_After_Message_Send_Internal	After	Server	At exit of WebLogic SIP Server code that writes messages to the wire.
Sip_Servlet_Around_Message_Send_Internal	Around	Server	At entry and exit of WebLogic SIP 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 Sip_Servlet_Before_Message_Send_Internal, you add monitor properties to define diagnostic actions.

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

Access the Administration Console for you domain.
Click Lock & Edit to start a new configuration session.
Select the Diagnostics->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 Diagnostics->Diagnostic Modules node and select instrumentationModule from the list of modules.
Select the Configuration->Instrumentation tab.
Select Enabled to enable instrumentation at the server level, then click Save.
Add the DyeInjection monitor to the module:

Click Add/Remove.
Select the name of a monitor from the Available list (for example, DyeInjection), and use the arrows to move it to the Chosen list.
Click OK.
Select the newly-created monitor from the list of available monitors.
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

Click Save

Add one or more delegate monitors to the module:

Click Add/Remove.
Select the name of a delegate monitor from the Available list (for example, Sip_Servlet_Before_Message_Send_Internal), and use the arrows to move it to the Chosen list.
Click OK.
Select the newly-created monitor from the list of available monitors.
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 Sip_Servlet_Before_Message_Send_Internal monitor, sample actions include the DisplayArgumentsAction, StackDumpAction, ThreadDumpAction, and TraceAction.
Select the check box to EnableDyeFiltering.
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.
Click Save

Note:

You can repeat the above steps to create additional delegate monitors.

Click Activate Changes to apply your 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. Listing 3-1 shows a sample configuration file that uses the Sip_Servlet_Before_Service monitor.

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

Operations Guide