Operations Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Using the WebLogic Server Diagnostic Framework (WLDF)

The following sections describe how Oracle Communications Converged Application Server is integrated with the WebLogic Diagnostic Framework (WLDF):

 

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

The sections that follow provide more details about how Oracle Communications Converged Application Server integrates with each of the above WLDF components. See Configuring and Using the WebLogic Diagnostics Framework in the Oracle WebLogic Server 10g Release 3 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 for information about using the WLDF console extension to collect and monitor diagnostic information.

 

Data Collection and Logging

Oracle Communications Converged Application 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: 

cp ~/bea/wlserver_10.3/server/lib/console-ext/diagnostics-console-extension.jar ~/bea/user_projects/domains/mydomain/console-ext

When accessing the WLDF console extension, the Oracle Communications Converged Application Server runtime MBean attributes are available in the Metrics tab of the extension. See Using the WebLogic Diagnostic Framework Console Extension in the Oracle WebLogic Server 10g Release 3 documentation for more information.

Oracle Communications 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 Developing SIP Applications. Note that a server restart is necessary in order to initiate independent logging and log rotation.

 

Watches and Notifications

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

 

Image Capture

Oracle Communications 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:

See Configure and capture diagnostic images in the Oracle WebLogic Server 10g Release 3 Administration Console Help for more information on generating diagnostic images.

 

Instrumentation

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

Oracle Communications Converged Application 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 Oracle WebLogic Server 10g Release 3 documentation.

Table 3-1 Oracle Communications Converged Application 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 Oracle WebLogic Server 10g Release 3 documentation for information about configuring the monitor.

Oracle Communications 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 3-2.

Table 3-2 Oracle Communications 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:
  1. Before and after calls to getSession and getApplicationSession of the SipServletMessage class hierarchy.
  2. 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 Oracle Communications Converged Application Server code that writes messages to the wire.
occas/Sip_Servlet_After_Message_Send_Internal
After
Server
At exit of Oracle Communications Converged Application Server code that writes messages to the wire.
occas/Sip_Servlet_Around_Message_Send_Internal
Around
Server
At entry and exit of Oracle Communications 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 Oracle Communications Converged Application Server DyeInjection monitor, a delegate monitor, and enable dye filtering:

  1. Access the Administration Console for you domain.
  2. Select the Diagnostics->Diagnostic Modules node in the left pane of the console.
  3. Click New to create a new Diagnostic Module. Give the module a descriptive name, such as “instrumentationModule,” and click OK.
  4. Select the new “instrumentationModule” from the list of modules in the table.
  5. Select the Targets tab.
  6. Select a server on which to target the module and click Save.
  7. Return to the Diagnostics->Diagnostic Modules node and select instrumentationModule from the list of modules.
  8. Select the Configuration->Instrumentation tab.
  9. Select Enabled to enable instrumentation at the server level, then click Save.
  10. 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: 
      6.           SIP_RES=180
                SIP_REQ=INVITE
                SIP_ANY_HEADER=request.Contact=sip:sipp@localhost:5061
    6. Click Save
  11. 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
      10. Note: You can repeat the above steps to create additional delegate monitors.

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 occas/Sip_Servlet_Before_Service monitor.

Listing 3-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 the Oracle WebLogic Server 10g Release 3 documentation for more information about creating the weblogic-diagnostics.xml configuration file.


  Back to Top       Previous  Next