What tools are available for diagnosing SOA Suite issues?
There are a variety of tools available to help you and Support diagnose SOA Suite issues in 11g but it can be confusing as to which tool is appropriate for a particular situation and what their
relationships are. This blog post will introduce
the various tools and attempt to clarify what each is for and how they are related. Let's first list
the tools we'll be addressing:
RDA: Remote Diagnostic Agent
DFW: Diagnostic Framework
Selective Tracing
DMS: Dynamic Monitoring Service
ODL: Oracle Diagnostic Logging
ADR: Automatic Diagnostics Repository
ADRCI: Automatic Diagnostics Repository Command Interpreter
WLDF: WebLogic Diagnostic Framework
This overview is not mean to be a comprehensive guide on using all of these tools, however, extensive reference materials are included that will provide many more details on their execution. Another
point to note is that all of these tools are applicable for Fusion Middleware as a whole but specific products may or may not have implemented features to leverage them.
A couple of
the tools have a WebLogic Scripting Tool or 'WLST' interface. WLST is a command interface for executing pre-built functions and custom scripts against a domain. A detailed
WLST tutorial is
beyond the scope of this post but you can find general information here.
There are more specific resources in
the below sections.
In this post when we refer to 'Enterprise Manager' or 'EM' we are referring to Enterprise Manager Fusion Middleware Control.
RDA (Remote Diagnostic Agent)
RDA is a standalone tool that is used to collect both static configuration and dynamic runtime information from
the SOA environment. RDA is generally
run manually from
the command line against a domain or single server. When opening a new Service Request, including an RDA collection can dramatically decrease
the back and forth required to
collect logs and configuration information for Support.
After installing RDA you configure it to use
the SOA Suite module as decribed in
the referenced resources.
The SOA module includes
the Oracle WebLogic Server (WLS) module by default in order to include all of
the relevant
information for
the environment. In addition to this basic configuration there is also an advanced mode where you can set
the number of thread dumps for
the collections, log files, Incidents, etc.
When would you use it?
When creating a Service Request or otherwise working with Oracle resources on an issue, capturing environment snapshots to baseline your configuration or to diagnose an issue on your own.
How is it related to
the other tools?
RDA is related to DFW in that it collects
the last 10 Incidents from
the server by default. In a similar manner, RDA is related to ODL through its collection of
the diagnostic logs and these may
contain information from Selective Tracing sessions.
Examples of what it currently collects: (for details please see
the links in
the Resources section)
Diagnostic Logs (ODL)
Diagnostic Framework Incidents (DFW)
SOA MDS Deployment Descriptors
SOA Repository Summary Statistics
Thread Dumps
Complete Domain Configuration
RDA Resources:
Webcast Recording: Using RDA with Oracle SOA Suite 11g
Blog Post: Diagnose SOA Suite 11g Issues Using RDA
Download RDA
How to Collect Analysis Information Using RDA for Oracle SOA Suite 11g
Products [ID 1350313.1]
How to Collect Analysis Information Using RDA for Oracle SOA Suite and
BPEL Process Manager 11g [ID 1352181.1]
Getting Started With Remote Diagnostic Agent: Case Study - Oracle
WebLogic Server (Video) [ID 1262157.1]
top
DFW (Diagnostic Framework)
DFW provides
the ability to collect specific information for a particular problem when that problem occurs. DFW is included with your SOA Suite installation and deployed to
the domain.
Let's define
the components of DFW.
Diagnostic Dumps: Specific diagnostic collections that are defined at either
the 'system' or product level. Examples would be diagnostic logs or thread dumps.
Incident: A collection of Diagnostic Dumps associated with a particular problem
Log Conditions: An Oracle Diagnostic Logging event that DFW is configured to listen for. If
the event is identified then an Incident will be created.
WLDF Watch:
The WebLogic Diagnostic Framework or 'WLDF' is not a component of DFW, however, it can be a source of DFW Incident creation through
the use of a 'Watch'.
WLDF Notification: A Notification is a component of WLDF and is
the link between
the Watch and DFW. You can configure multiple Notification types in WLDF and associate them
with your Watches. 'FMWDFW-notification' is available to you out of
the box to allow for DFW notification of Watch execution.
Rule: Defines a WLDF Watch or Log Condition for which we want to associate a set of Diagnostic Dumps. When triggered
the specified dumps will be collected and added to
the
Incident
Rule Action: Defines
the specific Diagnostic Dumps to collect for a particular rule
ADR: Automatic Diagnostics Repository; Defined for every server in a domain. This is where Incidents are stored
Now let's walk through a simple flow:
Oracle Web Services error message OWS-04086 (SOAP Fault) is generated on managed server 1
DFW Log Condition for OWS-04086 evaluates to TRUE
DFW creates a new Incident in
the ADR for managed server 1
DFW executes
the specified Diagnostic Dumps and adds
the output to
the Incident
In this case we'll grab
the diagnostic log and thread dump. We might also want to collect
the WSDL binding information and SOA audit trail
When would you use it?
When you want to automatically collect Diagnostic Dumps at a particular time using a trigger or when you want to manually collect
the information. In either case it can be readily uploaded to
Oracle Support through
the Service Request.
How is it related to
the other tools?
DFW generates Incidents which are collections of Diagnostic Dumps. One of
the system level Diagonstic Dumps collects
the current server diagnostic log which is generated by ODL and can contain
information from Selective Tracing sessions. Incidents are included in RDA collections by default and ADRCI is a tool that is used to package an Incident for upload to Oracle Support. In
addition, both ODL and DMS can be used to trigger Incident creation through DFW.
The conditions and rules for generating Incidents can become quite complicated and
the below resources go into more detail. A simpler approach to leveraging at least
the Diagnostic Dumps is through
WLST (WebLogic Scripting Tool) where there are commands to do
the following:
Create an Incident
Execute a single Diagnostic Dump
Describe a Diagnostic Dump
List
the available Diagnostic Dumps
The WLST option offers greater control in what is generated and when. It can be a great help when collecting information for Support. There are overlaps with RDA, however, DFW is geared
towards collecting specific runtime information when an issue occurs while existing Incidents are collected by RDA.
There are 3 WLDF Watches configured by default in a SOA Suite 11g domain: Stuck Threads, Unchecked Exception and Deadlock.
These Watches are enabled by default and will generate Incidents in ADR. They are configured to reset automatically after 30 seconds so they have
the potential to create multiple Incidents if these
conditions are consistent.
The Incidents generated by these Watches will only contain System level Diagnostic Dumps. These same System level Diagnostic Dumps will be included in any application
scoped Incident as well.
Starting in 11.1.1.6, SOA Suite is including its own set of application scoped Diagnostic Dumps that can be executed from WLST or through a WLDF Watch or Log Condition. These Diagnostic Dumps can be
added to an Incident such as in
the earlier example using
the error code OWS-04086.
soa.config: MDS configuration files and deployed-composites.xml
soa.composite: All artifacts related to
the deployed composite
soa.wsdl: Summary of endpoints configured for
the composite
soa.edn: EDN configuration summary if applicable
soa.db: Summary DB information for
the SOA repository
soa.env: Coherence cluster configuration summary
soa.composite.trail: Partial audit trail information for
the running composite
The current release of RDA has
the option to collect
the soa.wsdl and soa.composite Diagnostic Dumps. More Diagnostic Dumps for SOA Suite products are planned for future
releases along with enhancements to DFW itself.
DFW Resources:
Webcast Recording: SOA Diagnostics Sessions: Diagnostic Framework
Diagnostic Framework
Documentation
DFW WLST Command Reference
Documentation for SOA Diagnostic Dumps in 11.1.1.6
top
Selective Tracing
Selective Tracing is a facility available starting in version 11.1.1.4 that allows you to increase
the logging level for specific loggers and for a specific context. What this means is that you have
greater capability to collect needed diagnostic log information in a production environment with reduced overhead. For example, a Selective Tracing session can be executed that only increases
the log level for one composite, only one logger, limited to one server in
the cluster and for a preset period of time. In an environment where dozens of composites are deployed this can dramatically
reduce
the volume and overhead of
the logging without sacrificing relevance.
Selective Tracing can be administered either from Enterprise Manager or through WLST. WLST provides a bit more flexibility in terms of exactly where
the tracing is run.
When would you use it?
When there is an issue in production or another environment that lends itself to filtering by an available context criteria and increasing
the log level globally results in too much overhead or
irrelevant information.
The information is written to
the server diagnostic log and is exportable from Enterprise Manager
How is it related to
the other tools?
Selective Tracing output is written to
the server diagnostic log. This log can be collected by a system level Diagnostic Dump using DFW or through a default RDA collection. Selective Tracing also
heavily leverages ODL fields to determine what to trace and to tag information that is part of a particular tracing session.
Available Context Criteria:
Application Name
Client Address
Client Host
Composite Name
User Name
Web Service Name
Web Service Port
Selective Tracing Resources:
Webcast Recording: SOA Diagnostics Session: Using Selective Tracing to Diagnose SOA Suite Issues
How to Use Selective Tracing for SOA [ID 1367174.1]
Selective Tracing WLST Reference
top
DMS (Dynamic Monitoring Service)
DMS exposes runtime information for monitoring. This information can be monitored in two ways:
Through
the DMS servlet
As exposed MBeans
The servlet is deployed by default and can be accessed through http://<host>:<port>/dms/Spy (use administrative credentials to access).
The landing page of
the servlet shows identical columns of what
are known as Noun Types. If you select a Noun Type you will see a table in
the right frame that shows
the attributes (Sensors) for
the Noun Type and
the available instances. SOA Suite has several exposed Noun
Types that are available for viewing through
the Spy servlet. Screenshots of
the Spy servlet are available in
the Knowledge Base article
How to Monitor Runtime SOA Performance With
the Dynamic Monitoring Service (DMS).
Every Noun instance in
the runtime is exposed as an MBean instance. As such they are generally available through an MBean browser and available for monitoring through WLDF. You can configure a
WLDF Watch to monitor a particular attribute and fire a notification when
the threshold is exceeded. A WLDF Watch can use
the out of
the box DFW notification type to notify DFW to create an Incident.
When would you use it?
When you want to monitor a metric or set of metrics either manually or through an automated system. When you want to trigger a WLDF Watch based on a metric exposed through DMS.
How is it related to
the other tools?
DMS metrics can be monitored with WLDF Watches which can in turn notify DFW to create an Incident.
DMS Resources:
How to Monitor Runtime SOA Performance With
the Dynamic Monitoring Service (DMS) [ID 1368291.1]
How to Reset a SOA 11g DMS Metric
DMS
Documentation
top
ODL (Oracle Diagnostic Logging)
ODL is
the primary facility for most Fusion Middleware applications to log what they are doing. Whenever you change a logging level through Enterprise Manager it is ultimately exposed through ODL and
written to
the server diagnostic log. A notable exception to this is WebLogic Server which uses its own log format / file.
ODL logs entries in a consistent, structured way using predefined fields and name/value pairs. Here's an example of a SOA Suite entry:
[2012-04-25T12:49:28.083-06:00] [AdminServer] [ERROR] [] [oracle.soa.bpel.engine] [tid: [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)'] [userId: ] [ecid: 0963fdde7e77631c:-31a6431d:136eaa46cda:-8000-00000000000000b4,0] [errid: 41] [WEBSERVICE_PORT.name: BPELProcess2_pt] [APP: soa-infra] [composite_name: TestProject2] [J2EE_MODULE.name: fabric] [WEBSERVICE.name: bpelprocess1_client_ep] [J2EE_APP.name: soa-infra] Error occured while handling a post operation[[
When would you use it?
You'll use ODL almost every time you want to identify and diagnose a problem in
the environment.
The entries are written to
the server diagnostic log.
How is it related to
the other tools?
The server diagnostic logs are collected by DFW and RDA. Selective Tracing writes its information to
the diagnostic log as well.
Additionally, DFW log conditions are triggered by ODL log events.
ODL Resources:
ODL
Documentation
top
ADR (Automatic Diagnostics Repository)
ADR is not a tool in and of itself but is where DFW stores
the Incidents it creates. Every server in
the domain has an ADR location which can be found under <SERVER_HOME>/adr. This is referred to
the as
the ADR 'Base' location.
ADR also has what are known as 'Home' locations. Example:
You have a domain called 'myDomain' and an associated managed server called 'myServer'. Your admin server is called 'AdminServer'.
Your domain home directory is called 'myDomain' and it contains a 'servers' directory.
The 'servers' directory contains a directory for
the managed server called 'myServer' and here is where you'll find
the 'adr' directory which is
the ADR 'Base' location for myServer.
To get to
the ADR 'Home' locations we drill through a few levels: diag/ofm/myDomain/
In an 11.1.1.6 SOA Suite domain you will see 2 directories here, 'myServer' and 'soa-infra'. These are
the ADR 'Home' locations.
'myServer' is
the 'system' ADR home and contains system level Incidents.
'soa-infra' is
the name that SOA Suite used to register with DFW and this ADR home contains SOA Suite related Incidents
Each ADR home location contains a series of directories, one of which is called 'incident'. This is where your Incidents are stored.
When would you use it?
It's a good idea to check on these locations from time to time to see whether a lot of Incidents are being generated. They can be cleaned out by deleting
the Incident directories or through
the ADRCI
tool. If you know that an Incident is of particular interest for an issue you're working with Oracle you can simply zip it up and provide it.
How does it relate to
the other tools?
ADR is obviously very important for DFW since it's where
the Incidents are stored. Incidents contain Diagnostic Dumps that may relate to diagnostic logs (ODL) and DMS metrics.
The most recent 10 Incident directories are collected by RDA by default and ADRCI relies on
the ADR locations to help manage
the contents.
top
ADRCI (Automatic Diagnostics Repository Command Interpreter)
ADRCI is a command line tool for packaging and managing Incidents.
When would you use it?
When purging Incidents from an ADR Home location or when you want to package an Incident along with an offline RDA collection for upload to Oracle Support.
How does it relate to
the other tools?
ADRCI contains a tool called
the Incident Packaging System or IPS. This is used to package an Incident for upload to Oracle Support through a Service Request. Starting in 11.1.1.6 IPS will attempt
to collect an offline RDA collection and include it with
the Incident package. This will only work if Perl is available on
the path, otherwise it will give a warning and package only
the Incident
files.
ADRCI Resources:
How to Use
the Incident Packaging System (IPS) in SOA 11g [ID 1381259.1]
ADRCI
Documentation
top
WLDF (WebLogic Diagnostic Framework)
WLDF is functionality available in WebLogic Server since version 9. Starting with FMw 11g a link has been added between WLDF and
the pre-existing DFW,
the WLDF Watch Notification. Let's take a closer look
at
the flow:
There is a need to monitor
the performance of your SOA Suite message processing
A WLDF Watch is created in
the WLS console that will trigger if
the average message processing time exceeds 2 seconds. This metric is monitored through a DMS MBean instance.
The out of
the box DFW Notification (the Notification is called FMWDFW-notification) is added to
the Watch. Under
the covers this notification is of type JMX.
The Watch is triggered when
the threshold is exceeded and fires
the Notification.
DFW has a listener that picks up
the Notification and evaluates it according to its rules, etc
When it comes to automatic Incident creation, WLDF is a key component with capabilities that will grow over time.
When would you use it?
When you want to monitor
the WLS server log or an MBean metric for some condition and fire a notification when
the Watch is triggered.
How does it relate to
the other tools?
WLDF is used to automatically trigger Incident creation through DFW using
the DFW Notification.
WLDF Resources:
How to Monitor Runtime SOA Performance With
the Dynamic Monitoring Service (DMS) [ID 1368291.1]
How To Script
the Creation of a SOA WLDF Watch in 11g [ID 1377986.1]
WLDF
Documentation
top
