<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
  ~  Copyright (c) 2005-2010, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~  WSO2 Inc. licenses this file to you under the Apache License,
  ~  Version 2.0 (the "License"); you may not use this file except
  ~  in compliance with the License.
  ~  You may obtain a copy of the License at
  ~
  ~    http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<!DOCTYPE html
        PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" >

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
    <title>
      Monitoring WSO2 ESB
    </title>
    <link href="css/esb-docs.css" rel="stylesheet"/>
    <link href="styles/dist-docs.css" rel="stylesheet" type="text/css" media="all"/>
  </head>
  <body>
    [
    <a href="docs_index.html">Documentation Index</a>
    ]
    <h1>
      Monitoring WSO2 Enterprise Service Bus (ESB)
    </h1>
    <p>
      This guide describes how to monitor WSO2 ESB using Mediation Statistics component and
      Java Management Extensions (JMX). WSO2 ESB provides convenient, yet powerful mechanisms for
      monitoring an ESB deployment. Results provided by ESB Monitoring can be used to tune up
      message flows, detect mediation faults and track usage patterns.
    </p>
    <h2>Contents</h2>
    <div class="toc">
      <ul>
        <li>
          <a href="#Intro">Introduction</a>
        </li>
        <li>
          <a href="#MediationStats">Mediation Statistics</a>
          <ul>
            <li>
              <a href="#EnablingMediationStats">Enabling Mediation Statistics</a>
            </li>
            <li>
              <a href="#ViewingMediationStats">Viewing Mediation Statistics</a>
            </li>
          </ul>
        </li>
        <li>
          <a href="#otherMonitoring">Transport Statistics, System Statistics and System Logs</a>
        </li>
        <li>
          <a href="#JMXMonitoring">JMX Monitoring</a>
          <ul>
            <li>
              <a href="#UsingJCon">Using JConsole for JMX Monitoring</a>
            </li>
            <li>
              <a href="#MBeansSummary">Attributes and Operations of MBeans</a>
            </li>
          </ul>
        </li>
      </ul>
    </div>
    <p/>
    <h2 id="Intro">
      Introduction
    </h2>
    <p>
      WSO2 ESB provides variety of options to monitor and manage the server runtime. While it
      provides number of monitoring tools through the Web-based Management Console, WSO2 ESB also
      supports Java Management Extensions (JMX) way of monitoring.
    </p>
    <p/>
    <p/>
    <h2 id="MediationStats">
      Mediation Statistics
    </h2>
    <p>
      Out of monitoring capabilities of WSO2 ESB, the Mediation Statistics feature stands out as
      one of the most useful and widely used features. From functional components of the ESB,
      sequences, proxy services and endpoints directly get involved in processing messages. The
      Mediation Statistics feature enables a server administrator to collect runtime statistical
      information on these three types of functional components and view them through the
      Management Console. This feature provides a simple but effective way of determining the
      runtime performance of the ESB. The collected statistical data can be used to analyze network
      traffic patterns and draw rough estimates on how the service bus will be used in the future.
      Perhaps the most enticing attribute of the mediation statistics feature is that it can be
      configured in a fine grained manner. In other words, it allows a user to collect data on only
      a specified set of sequences, proxy services and endpoints.
    </p>
    <p>
      Mediation Statistics component of WSO2 ESB uses an in-memory data store to keep the
      collected data. The memory usage of the data store is restricted by the total number of
      statistics collecting proxy services, sequences and endpoints. If the number of proxy
      services, sequences and endpoints is constant, the memory usage of the mediation statistics
      component stays constant.

      Mediation Statistics component also supports persistence as an optional feature. That is,
      one may configure the ESB to save statistics to the WSO2 Governance Registry instance that
      comes embedded with the ESB. Mediation Statistics API allows easy sharing of collected
      data, among Carbon components. Currently WSO2 Business Activity Monitor (BAM) makes use of
      this API to access data collected by the service bus. Users can also develop custom data
      consumers to retrieve mediation statistics from the in-memory data store and process them
      further, using this API.
    </p>

    <h3 id="EnablingMediationStats">
      Enabling Mediation Statistics
    </h3>
    <p>
      Mediation Statistics feature is available with WSO2 ESB out of the box. You do not have to
      configure anything to use this feature. Simply sign-in to the Management Console and enable
      statistics on the sequences, proxy services and endpoints you want to monitor, and the service
      bus will start collecting data on them. For an example, in order to enable statistics for a
      sequence, click on <strong>Service Bus > Sequences</strong> in the left menu and simply click
      on the <strong>Enable Statistics</strong> icon corresponding to that sequence.
    </p>
    <p/>

    <p>
      <img alt="Enabling Mediation Statistics" src="images/monitoring_seq.png"/>
    </p>
    <p>Figure 1: Enabling mediation statistics for a sequence</p>
    <p/>

    <p>
      To enable statistics for a mediation component using the Synapse configuration language, set
      the value of the "statistics" attribute to "enabled" on the sequence, proxy or endpoint
      configuration.
    </p>

    <h3 id="ViewingMediationStats">
      Viewing Mediation Statistics
    </h3>
    <p>
      To view the gathered statistics, click <strong>Monitor > Mediation Statistics</strong>.
      You will be shown a graphical summary of all collected statistics.
    </p>

    <p>
      <img alt="Viewing Mediation Statistics" src="images/monitoring_view.png"/>
    </p>
    <p>Figure 2: Viewing mediation statistics</p>
    <p/>

    <p>
      Starting from this view, you can drill down to see more fine grained data such as statistics
      pertaining to a single sequence or a proxy service. You can even get statistics for different
      operations on the same endpoint. Click <strong>Proxy Service Statistics</strong> link in the
      upper right corner box of the UI shown in Figure 2 to view a summary of Proxy Service Statistics
      (Figure 3)
    </p>

    <p>
      <img alt="Viewing Mediation Statistics" src="images/monitoring_view_ps.png"/>
    </p>
    <p>Figure 3: Mediation statistics of all proxy services</p>
    <p/>

    <p>
        Select a proxy service from the "Proxy Services" list shown above to view statistics of that
        proxy service.
    </p>

    <p>
      <img alt="Viewing Mediation Statistics" src="images/monitoring_view_ps_single.png"/>
    </p>
    <p>Figure 4: Mediation statistics of a proxy service</p>
    <p/>
    <p/>
    <h2 id="otherMonitoring">Transport Statistics, System Statistics and System Logs</h2>
    <p>
      WSO2 ESB Management Console provides ways to monitor
      <a href="statistics/docs/userguide.html">
      System Statistics</a>, <a href="transport/docs/userguide.html">Transport Statistics</a> and
      <a href="log-view/docs/userguide.html">System Logs</a>.
    </p>
    <p>
      <a href="tracer/docs/userguide.html">SOAP Tracer</a> and
      <a href="mediation-tracer/docs/userguide.html">Mediation Tracer</a> are some additional
      monitoring tools provided by WSO2 ESB.
    </p>
    <p/>
    <h2 id="JMXMonitoring">
      JMX Monitoring
    </h2>
    <p>
      WSO2 ESB exposes number of management resources as JMX MBeans that can be used for managing
      and monitoring the running server. These MBeans can be accessed remotely using a JMX client
      such as JConsole. When WSO2 ESB is starting up, it will display the JMX Service URL in the
      console as follows.
    </p>
    <pre xml:space="preserve">
    INFO - JMXServerManager JMX Service URL :         service:jmx:rmi://localhost:11111/jndi/rmi://localhost:9999/jmxrmi
    </pre>
    <p>
      This URL can be used to remotely access the JMX Service exposed by WSO2 ESB. In this guide,
      we will use JConsole as the JMX client to access this service.
    </p>
    <h3 id="UsingJCon">
      Using JConsole for JMX Monitoring
    </h3>
    <p>
      Start JConsole and enter the above URL as the JMX Service URL. Type "admin" in both
      username and password fields and click "Connect".
    </p>
    <p>
      <img alt="JConsole Login" src="images/monitoring_jconsole_login.png"/>
    </p>
    <p>Figure 5: Connecting to the JMX service using JConsole</p>
    <p/>

    <p>
      After successfully connecting to the JMX service, click on "MBeans" tab of JConsole to view
      MBeans exposed by the ESB. As shown in Figure 6, these are listed under org.apache.axis2
      and org.apache.synapse nodes. The following section summarizes the attributes and operations
      available in MBeans exposed by the WSO2 ESB.
    </p>
    <p>
      <img alt="JConsole Login" src="images/monitoring_jconsole_mbeans.png"/>
    </p>
    <p>Figure 6: Viewing MBeans exposed by WSO2 ESB</p>
    <p/>
    <h3 id="MBeansSummary">
      Attributes and Operations of MBeans
    </h3>

    <ul>
      <li>Transport related MBeans: For each transport listener and sender enabled in the
        ESB, there will be an MBean under org.apache.axis2/Transport node which has following
        attributes and operations. For example, when http and https transports are enabled following
        MBeans will be exposed.
        <ul>
          <li>org.apache.axis2/Transport/nio-http-listener</li>
          <li>org.apache.axis2/Transport/nio-http-sender</li>
          <li>org.apache.axis2/Transport/nio-https-listener</li>
          <li>org.apache.axis2/Transport/nio-https-sender</li>
        </ul>
        <p/>
        <table width="100%">
          <thead>
            <tr>
              <td width="30%">
                <strong>Attribute/Operation Name</strong>
              </td>
              <td width="70%">
                <strong>Description</strong>
              </td>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>ActiveThreadCount</td>
              <td>Threads active in this transport listener/sender.</td>
            </tr>
            <tr>
              <td>AvgSizeReceived</td>
              <td>Average size of received messages.</td>
            </tr>
            <tr>
              <td>AvgSizeSent</td>
              <td>Average size of sent messages.</td>
            </tr>
            <tr>
              <td>MaxSizeReceived</td>
              <td>Maximum message size of received messages.</td>
            </tr>
            <tr>
              <td>MaxSizeSent</td>
              <td>Maximum message size of sent messages.</td>
            </tr>
            <tr>
              <td>MinSizeReceived</td>
              <td>Minimum message size of received messages.</td>
            </tr>
            <tr>
              <td>MinSizeSent</td>
              <td>Minimum message size of sent messages.</td>
            </tr>
            <tr>
              <td>MessagesReceived</td>
              <td>Total number of messages received through this transport.</td>
            </tr>
            <tr>
              <td>MessagesSent</td>
              <td>Total number of messages sent through this transport.</td>
            </tr>
            <tr>
              <td>FaultsReceiving</td>
              <td>Number of faults encountered while receiving.</td>
            </tr>
            <tr>
              <td>FaultsSending</td>
              <td>Number of faults encountered while sending.</td>
            </tr>
            <tr>
              <td>BytesReceived</td>
              <td>Number of bytes received through this transport.</td>
            </tr>
            <tr>
              <td>BytesSent</td>
              <td>Number of bytes sent through this transport.</td>
            </tr>
            <tr>
              <td>QueueSize</td>
              <td>Number of messages currently queued. Messages get queued if all the worker threads
              in this transport thread pool are busy.
              </td>
            </tr>
            <tr>
              <td>ResponseCodeTable</td>
              <td>Number of messages sent against their response codes.
              </td>
            </tr>
            <tr>
              <td>TimeoutsReceiving</td>
              <td>Message receiving timeout.</td>
            </tr>
            <tr>
              <td>TimeoutsSending</td>
              <td>Message sending timeout.</td>
            </tr>
            <tr>
              <td>LastResetTime</td>
              <td>Last time transport listener/sender statistic recording was reset.
              </td>
            </tr>
            <tr>
              <td>MetricsWindow</td>
              <td>Time difference between current time and last reset time in milliseconds.</td>
            </tr>
            <tr>
              <td>resetStatistics()</td>
              <td>Clear recorded transport listener/sender statistics and restart recording.</td>
            </tr>
            <tr>
              <td>start()</td>
              <td>Start this transport listener/sender.</td>
            </tr>
            <tr>
              <td>stop()</td>
              <td>Stop this transport listener/sender.</td>
            </tr>
            <tr>
              <td>pause()</td>
              <td>Pause this transport listener/sender which has been started.</td>
            </tr>
            <tr>
              <td>resume()</td>
              <td>Resume this transport listener/sender which is currently paused.</td>
            </tr>
            <tr>
              <td>maintenenceShutdown(long gracePeriod)</td>
              <td>Stop processing new messages, and wait the specified maximum time for in-flight
                requests to complete before a controlled shutdown for maintenence.</td>
            </tr>
          </tbody>
        </table>
        <p/>
        <p/>
      </li>
      <li>Latency related MBeans:
        <p/>
        <ul>
          <li>org.apache.synapse/NHTTPLatencyView/nio-http</li>
          <li>org.apache.synapse/NHTTPLatencyView/nio-https</li>
          <li>org.apache.synapse/NHTTPS2SLatencyView/nio-http</li>
          <li>org.apache.synapse/NHTTPS2SLatencyView/nio-https</li>
        </ul>
        <p/>
        <table width="100%">
          <thead>
            <tr>
              <td width="30%">
                <strong>Attribute/Operation Name</strong>
              </td>
              <td width="70%">
                <strong>Description</strong>
              </td>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>AllTimeAvgLatency</td>
              <td>Average latency since latency recording was last reset.</td>
            </tr>
            <tr>
              <td>LastXxxAvgLatency</td>
              <td>Average latency for last Xxx time period. For example,
                LastHourAvgLatency return the average latency for last hour.
              </td>
            </tr>
            <tr>
              <td>LastResetTime</td>
              <td>Last time latency statistic recording was reset.</td>
            </tr>
            <tr>
              <td>reset()</td>
              <td>Clear recorded latency statistics and restart recording.</td>
            </tr>
          </tbody>
        </table>
        <p/>
        <p/>
      </li>
      <li>
        NttpConnections related MBeans:
        <p/>
        <ul>
          <li>org.apache.synapse/NhttpConnections/http-listener</li>
          <li>org.apache.synapse/NhttpConnections/http-sender</li>
          <li>org.apache.synapse/NhttpConnections/https-listener</li>
          <li>org.apache.synapse/NhttpConnections/https-sender</li>
        </ul>
        <p/>
        <table width="100%">
          <thead>
            <tr>
              <td width="30%">
                <strong>Attribute/Operation Name</strong>
              </td>
              <td width="70%">
                <strong>Description</strong>
              </td>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>ActiveConnections</td>
              <td>Number of currently active connections.</td>
            </tr>
            <tr>
              <td>ActiveConnectionsPerHosts</td>
              <td>A map of number of connections against hosts.</td>
            </tr>
            <tr>
              <td>LastXxxConnections</td>
              <td>Number of connections created during last Xxx time period.</td>
            </tr>
            <tr>
              <td>RequestSizesMap</td>
              <td>A map of number of requests against their sizes.</td>
            </tr>
            <tr>
              <td>ResponseSizesMap</td>
              <td>A map of number of responses against their sizes.</td>
            </tr>
            <tr>
              <td>LastResetTime</td>
              <td>Last time connection statistic recordings was reset.</td>
            </tr>
            <tr>
              <td>reset()</td>
              <td>Clear recorded connection statistics and restart recording.</td>
            </tr>
          </tbody>
        </table>
        <p/>
        <p/>
      </li>

      <li>
        Threading related MBeans:
        <p/>
        <ul>
          <li>org.apache.synapse/Threading/HttpClientWorker</li>
          <li>org.apache.synapse/Threading/HttpServerWorker</li>
        </ul>
        <p/>
        <table width="100%">
          <thead>
            <tr>
              <td width="30%">
                <strong>Attribute/Operation Name</strong>
              </td>
              <td width="70%">
                <strong>Description</strong>
              </td>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>TotalWorkerCount</td>
              <td>Total worker threads related to this server/client.</td>
            </tr>
            <tr>
              <td>AvgUnblockedWorkerPercentage</td>
              <td>Time-averaged unblocked worker thread percentage.</td>
            </tr>
            <tr>
              <td>AvgBlockedWorkerPercentage</td>
              <td>Time-averaged blocked worker thread percentage.</td>
            </tr>
            <tr>
              <td>LastXxxBlockedWorkerPercentage</td>
              <td>Blocked worker thread percentage averaged for last Xxx time period.</td>
            </tr>
            <tr>
              <td>DeadLockedWorkers</td>
              <td>Number of deadlocked worker threads since last statistics reset.</td>
            </tr>
            <tr>
              <td>LastResetTime</td>
              <td>Last time thread statistic recordings was reset.</td>
            </tr>
            <tr>
              <td>reset()</td>
              <td>Clear recorded thread statistic and restart recording.</td>
            </tr>
          </tbody>
        </table>
      </li>

    </ul>

  </body>
</html>
