7 Monitoring RESTful Web Services and Clients

Oracle WebLogic Server supports a number of ways to monitor Java EE web services that conform to the Representational State Transfer (REST) architectural style using Java API for RESTful Web Services (JAX-RS).

About Monitoring RESTful Web Services

WebLogic Server provides several runtime MBeans that capture runtime information and let you monitor runtime statistics for your RESTful web service applications. Application monitoring is useful when you need to identify the performance hotspots in your JAX-RS application, observe execution statistics of particular resources, or listen to application or request lifecycle events.

You can use the methods defined in Table 7-1 to monitor your RESTful web service applications.

Table 7-1 Methods for Monitoring RESTful Web Services

Method Description

Fusion Middleware Control Enterprise Manager

Access runtime information and monitor runtime statistics, as described in Monitoring RESTful Web Services Using Enterprise Manager Fusion Middleware Control.

WebLogic Server Administration Console

Access runtime information and monitor runtime statistics, as described in Monitoring RESTful Web Services Using the Administration Console.

WebLogic Scripting Tool (WLST)

Access runtime information and monitor runtime statistics, as described in Monitoring RESTful Web Services Using WLST.

Logging filter

Monitor how a request is processed and dispatched to Jersey JAX-RS RI components, as described in Enabling the Tracing Feature.

In addition to the monitoring methods described in Table 7-1, Jersey 2.x (JAX-RS 2.0 RI) provides additional monitoring features, including support for event listeners and statistics monitoring. See Monitoring Jersey Applications in the Jersey 2.22 User Guide.

Note:

RESTful web service monitoring is enabled by default. In some cases, this may result in increased memory consumption. You can disable the monitoring feature at the domain level, and at the application level. See Disabling RESTful Web Service Application Monitoring.

Monitoring RESTful Web Services Using Enterprise Manager Fusion Middleware Control

Using Enterprise Manager Fusion Middleware Control, you can monitor runtime statistics for your RESTful Applications and resources, such as error and invocation counts, execution times, and so on. For complete information, see Monitoring Web Services in Administering Web Services.

Monitoring RESTful Web Services Using the Administration Console

Using the WebLogic Server Administration Console, you can monitor enhanced runtime statistics for your RESTful applications and resources, including detailed deployment and configuration data, global execution statistics, and resource and resource method execution statistics.

To monitor your deployed RESTful web services using the WebLogic Server Administration Console, follow these steps:

  1. Invoke the WebLogic Server Administration Console in your browser using the following URL:
    http://[host]:[port]/console
    

    where:

    • host refers to the computer on which WebLogic Server is running.

    • port refers to the port number on which WebLogic Server is listening (default value is 7001).

  2. Follow the procedure described in Monitor RESTful Web services in Oracle WebLogic Server Administration Console Online Help.

Monitoring RESTful Web Services Using WLST

You can use WLST to monitor the runtime MBeans that capture runtime information and runtime statistics for your RESTful web service applications. These MBeans are listed and described in Table 7-2.

Table 7-2 Runtime MBeans for Monitoring RESTful Web Services

Runtime MBean Description

ExceptionMapperStatistics

Displays monitoring information about the RESTful web service application exception mapper executions. See JaxRsExceptionMapperStatisticsRuntimeMBean in MBean Reference for Oracle WebLogic Server.

JaxRsApplication

Displays monitoring information for the RESTful web service application. See JaxRsApplicationRuntimeBean in MBean Reference for Oracle WebLogic Server.

RequestStatistics

Displays monitoring information about requests executed by the RESTful web service application. The statistics apply to all requests handled by the application and are not bound to any specific resource or resource method. See JaxRsExecutionStatisticsRuntimeMBean in MBean Reference for Oracle WebLogic Server.

ResourceConfig

Displays monitoring information about the RESTful web service application resource configuration. See JaxRsResourceConfigTypeRuntimeBean inMBean Reference for Oracle WebLogic Server.

Note: The JaxRsResourceConfigTypeRuntimeBean is deprecated in this release of WebLogic Server. You should use the Properties and ApplicationClass attributes of the JaxRsApplicationRuntimeMBean instead. See JaxRsApplicationRuntimeBean inMBean Reference for Oracle WebLogic Server.

ResponseStatistics

Displays monitoring information about responses created by the RESTful web service application. The statistics apply to all responses created by the application and are not bound to any specific resource or resource method. See JaxRsResponseStatisticsRuntimeMBean in MBean Reference for Oracle WebLogic Server.

RootResources

Displays monitoring information about the RESTful web service resource. Any object that is managed by a container (such as EJB) will have application scope. All other resources by default will have request scope. See JaxRsResourceRuntimeMBeanin MBean Reference for Oracle WebLogic Server.

Note: This MBean is deprecated in this release of WebLogic Server. You should use RootResourcesByClass instead.

RootResourcesByClass

Displays monitoring information for each resource class that is deployed in the RESTful web service application. One resource class can serve requests matched to different URIs. The array contains resource classes that are registered in the resource model plus resource classes of sub resources returned from sub resource locators. See JaxRsResourceRuntimeMBean inMBean Reference for Oracle WebLogic Server.

RootResourcesbyURI

Displays monitoring information for each URI that is exposed in the RESTful web service application. See JaxRsUriRuntimeMBean in MBean Reference for Oracle WebLogic Server.

Servlet

Displays monitoring information for the servlet that hosts the RESTful web service application. See ServletRuntimeMBean in MBean Reference for Oracle WebLogic Server.

To monitor RESTful web services using WLST, perform the steps provided in the following procedure.

In this procedure, the example steps provided demonstrate how to monitor the JAX-RS 2.0 Asynchronous Processing sample delivered with the WebLogic Server Samples Server, described at Sample Applications and Code Examples in Understanding Oracle WebLogic Server.

  1. Invoke WLST, as described in "Invoking WLST" in Understanding the WebLogic Scripting Tool.

    For example:

    c:\Oracle\oracle_common\common\bin> wlst
    
  2. Connect to the Administration Server instance, as described in connect in WLST Command Reference for WebLogic Server.

    For example:

    wls:/offline> connect('weblogic','password','t3://localhost:8001') 
    
  3. Navigate to the server runtime MBean, as described in serverRuntime in WLST Command Reference for WebLogic Server.

    For example:

    wls:/samples/serverConfig> serverRuntime()
    
    Location changed to serverRuntime tree. This is a read-only tree
    with ServerRuntimeMBean as the root.
    For more help, use help('serverRuntime')
    
    wls:/samples/serverRuntime> 
    
  4. Navigate to the Web application component runtime MBean.

    For example, to navigate to runtime MBean for the application named jaxrs-async:

    wls:/samples/serverRuntime> cd('ApplicationRuntimes/jaxrs-async')
    wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async> cd('ComponentRuntimes')
    wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs/ComponentRuntimes> cd ('AdminServer_/jaxrs-async')
    
  5. Navigate to the application runtime MBean for the RESTful web service request statistics.

    For example:

    wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes> cd ('AdminServer_/jaxrs-async'
    wls:/samples_domain/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes/AdminServer_/jaxrs-async>
    cd ('JaxRsApplications/examples.javaee7.jaxrs.async.MessageApplication/RequestStatistics/examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics')
    
  6. Review the monitoring information displayed for the RESTful web service application. See JaxRsApplicationRuntimeBean in MBean Reference for Oracle WebLogic Server.

    For example:

    wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes/AdminServer_/jaxrs-async
    /JaxRsApplications/examples.javaee7.jaxrs.async.MessageApplication/RequestStatistics
    /examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics> 
    ls()
    -r--   AvgTimeLast15m                               -1
    -r--   AvgTimeLast15s                               -1
    -r--   AvgTimeLast1h                                -1
    -r--   AvgTimeLast1m                                -1
    -r--   AvgTimeLast1s                                -1
    -r--   AvgTimeTotal                                 0
    -r--   MaxTimeLast15m                               -1
    -r--   MaxTimeLast15s                               -1
    -r--   MaxTimeLast1h                                -1
    -r--   MaxTimeLast1m                                -1
    -r--   MaxTimeLast1s                                -1
    -r--   MaxTimeTotal                                 0
    -r--   MinTimeLast15m                               -1
    -r--   MinTimeLast15s                               -1
    -r--   MinTimeLast1h                                -1
    -r--   MinTimeLast1m                                -1
    -r--   MinTimeLast1s                                -1
    -r--   MinTimeTotal                                 0
    -r--   Name                                         examples.javaee7.jaxrs.async.MessageApplication_RequestStatisti
    cs
    -r--   RequestCountLast15m                          0
    -r--   RequestCountLast15s                          0
    -r--   RequestCountLast1h                           0
    -r--   RequestCountLast1m                           0
    -r--   RequestCountLast1s                           0
    -r--   RequestCountTotal                            0
    -r--   RequestRateLast15m                           0.0
    -r--   RequestRateLast15s                           0.0
    -r--   RequestRateLast1h                            0.0
    -r--   RequestRateLast1m                            0.0
    -r--   RequestRateLast1s                            0.0
    -r--   RequestRateTotal                             0.0
    -r--   Type                                         JaxRsExecutionStatisticsRuntime
     
    wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes/AdminServer_/jaxrs-async
    /JaxRsApplications/examples.javaee7.jaxrs.async.MessageApplication/RequestStatistics
    /examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics>
    
  7. Navigate to any of the other runtime MBeans described in Table 7-2 to view additional monitoring information.

  8. Exit WLST, as described in Exiting WLST in Understanding the WebLogic Scripting Tool.

    For example:

    wls:/samples/serverRuntime/ApplicationRuntimes/jaxrs-async/ComponentRuntimes/AdminServer_/jaxrs-async
    /JaxRsApplications/examples.javaee7.jaxrs.async.MessageApplication/RequestStatistics
    /examples.javaee7.jaxrs.async.MessageApplication_RequestStatistics>exit()
    Exiting WebLogic Scripting Tool.
    c:\>
    

Enabling the Tracing Feature

The Jersey tracing feature provides useful information that describes how a request is processed and dispatched to Jersey JAX-RS RI components. Trace messages are output in the same order as they occur, so the numbering is useful to reconstruct the tracing order.

When enabled, the Jersey 2.x tracing facility collects useful information for individual requests from all components of the JAX-RS server-side request processing pipeline. The information collected may provide vital details for troubleshooting your Jersey or JAX-RS application.

The tracing information for a single request is returned to the requesting client in the HTTP headers of the response. In addition, the information is logged on the server-side using a dedicated Java Logger instance.

For more information about enabling the Jersey 2.x tracing facility, see Tracing Support in Jersey 2.22 User Guide.

Disabling RESTful Web Service Application Monitoring

You can disable monitoring for an individual Jersey 2.x Java API for RESTful Web Services (JAX-RS) application, or globally for an entire WebLogic domain.

For example, you can disable monitoring in the following ways:

WebLogic Server uses the following algorithm to determine whether monitoring should be enabled or disabled for each application.

  1. WebLogic Server checks the JAX-RS application property jersey.config.wls.server.monitoring.enabled.

    If it is set for the application, then WebLogic Server uses this value to determine if monitoring should be enabled or disabled for the application. If this value is not set, it proceeds to the next step.

  2. WebLogic Server checks the configuration MBean WebAppComponentMBean.JaxRsMonitoringDefaultBehavior property for the individual application.

    If it is set for the application, then WebLogic Server uses this value to determine if monitoring should be enabled or disabled for the application. If this value is not set, it proceeds to the next step.

  3. WebLogic Server checks the configuration MBean WebAppContainerMBean.JaxRsMonitoringDefaultBehavior property setting for the domain.

    If it is set for the domain, then WebLogic Server uses this value to determine if monitoring should be enabled or disabled for the application. If this value is not set, it proceeds to the next step.

  4. WebLogic Server uses the default setting, which is to enable JAX-RS monitoring for the application if none of the configuration properties in the previous steps have been set.

Disabling Monitoring for a RESTful Web Service Application Using Jersey Property

Jersey 2.x supports the following WebLogic Server-specific property that you can use to disable application monitoring for an individual RESTful web service application:

jersey.config.wls.server.monitoring.enabled

Setting this property to false disables monitoring in the application. You can set this property programmatically in the JAX-RS application subclass code, or declaratively via Servlet init parameters specified in the web.xml as shown in the following examples.

For convenience, the property name is stored in the weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_ENABLED constant field.

Example 7-1 provides an example of how you can disable monitoring programmatically in a RESTful web service application by extending the JAX-RS Application class.

Example 7-1 Disable Application Monitoring Programmatically by Extending the JAX-RS Application Class

ApplicationPath("/")
public class MyApplication extends Application {
 
  public Map<String, Object> getProperties() {
    final Map<String, Object> properties = new HashMap<>();
    // Disable JAX-RS Application monitoring (and WLS console monitoring) for this internal application.
    properties.put(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_ENABLED, false);
 
    return properties;
  }
}

Example 7-2 provides an example of how you can disable monitoring programmatically in a RESTful web service application by extending the JAX-RS Jersey ResourceConfig class.

Example 7-2 Disable Application Monitoring Programmatically by Extending the Jersey ResourceConfig Class

@ApplicationPath("/")
public class MyApplication extends ResourceConfig {
 
  public MyApplication() {
    // ...
 
    // Disable JAX-RS Application monitoring (and WLS console monitoring) for this internal application.
    property(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_ENABLED, false);
  }
 
  // ...
}

Example 7-3 provides an example of how you can disable monitoring declaratively using Servlet init parameters specified in the web.xml.

Example 7-3 Disable Application Monitoring Declaratively Using Servlet Init Parameters in web.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="2.5"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
 
  <servlet>
    <servlet-name>com.examples.MyApplication</servlet-name>
    ...
    <init-param>
      <param-name>jersey.config.wls.server.monitoring.enabled</param-name>
      <param-value>false</param-value>
    </init-param>
    ...
    <load-on-startup>1</load-on-startup>
  </servlet>
 
  <servlet-mapping>
    <servlet-name>com.examples.MyApplication</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

Disabling Monitoring for a RESTful Web Service Application Using WebLogic Configuration MBean

After you have deployed a RESTful web service application on WebLogic Server, you can disable monitoring of the application by using WLST, for example, to set the JaxRsMonitoringDefaultBehavior property to false on its WebAppComponentMBean:

webAppComponentMBean.setJaxRsMonitoringDefaultBehavior("false")

This is a per-application property that is internally used by Jersey/WebLogic integration code to determine the state of the default monitoring behavior in the JAX-RS application:

  • If set to true, monitoring for the JAX-RS application is enabled.

  • If set to false, monitoring for the JAX-RS application is disabled.

  • If the property is not set, then the domain-level Web Application Container property WebAppContainerMBean.isJaxRsMonitoringDefaultBehavior()) is used as a fall-back.

Note:

The value of this application-specific property (if set) overrides the value of domain-level configuration property.

By default the value is not explicitly set.

Disabling RESTful Web Service Application Monitoring for a WebLogic Domain

Application monitoring is enabled by default for all RESTful web service applications deployed to a WebLogic domain. It is possible to reverse this default behavior in a WebLogic domain and disable JAX-RS monitoring for all RESTful web service applications deployed in the domain (unless overridden by an application-specific configuration) by setting the JaxRsMonitoringDefaultBehavior property on WebAppContainerMBean to false:

WebAppContainerMBean.setJaxRsMonitoringDefaultBehavior("false")

This Web Application Container property is a domain-level property used by Jersey/WebLogic integration code to determine the behavior of monitoring in JAX-RS applications at the domain level:

  • If set to true (or not set), then JAX-RS monitoring is enabled (if not overridden by properties set directly in an application). By default this property is not set explicitly and monitoring is enabled.

  • If set to false, then monitoring for all JAX-RS applications is disabled by default for the given domain.

Note:

You can override this domain-level setting in each JAX-RS application by setting similar properties, WebAppComponentMBean#isJaxRsMonitoringDefaultBehavior()), at the application level. See Disabling Monitoring for a RESTful Web Service Application Using WebLogic Configuration MBean.

You can update the WebAppContainerMBean.JaxRsMonitoringDefaultBehavior property for the domain using WLST commands before starting the domain, or before deploying any applications, as shown in Example 7-4.

Example 7-4 provides a sample WLST script that disables JAX-RS monitoring for the entire domain by default.

Example 7-4 Sample WLST Script for Disabling JAX-RS Monitoring at Domain Level

connect(<user>, <password>)    
edit()
startEdit()
cd("WebAppContainer/<domain_name>/")
cmo.setJaxRsMonitoringDefaultBehavior(false)
activate()

Note:

You must restart the domain after you disable monitoring to ensure that all previously deployed applications are redeployed with the new setting.

[Example 7-5 shows a section of the resulting domain configuration document at DOMAIN_NAME/config/config.xml after you have changed the jax-rs-monitoring-default-behavior setting to false.

Example 7-5 config.xml file with JAX-RS Monitoring Disabled at the Domain Level

<?xml version='1.0' encoding='UTF-8'?>
<domain ...>
  <name>mydomain</name>
  ...
  <web-app-container>
    <jax-rs-monitoring-default-behavior>false
</jax-rs-monitoring-default-behavior>
  </web-app-container>
  ...
</domain>

Note:

Although it is possible to do so, Oracle does not recommend editing the config.xml file directly. See Domain Configuration Files in Understanding Domain Configuration for Oracle WebLogic Server.

Enable Monitoring of Synthetic Jersey Resources in a RESTful Web Service Application

When a RESTful web service application is deployed on WebLogic Server, the Jersey runtime (to satisfy JAX-RS specification requirements) introspects all the application resources and eventually extends the resource model of the application with additional synthetic resources and/or resource methods. For example, synthetic resources and resource methods are added to support:
  • Resources exposing the WADL for the entire JAX-RS application, as well as a partial WADL for any deployed resource.

  • OPTIONS method handlers for each resource or resource method of the JAX-RS application.

  • HEAD method handlers for each resource or resource method of the JAX-RS application.

Depending on the application, it is possible that quite a lot of additional synthetic resources may get added to a deployed application. For performance reasons, WebLogic Server, by default, does not expose runtime MBeans for these extended synthetic resources and resource methods.

You can, however, display information about these additional synthetic resources in the WebLogic Server Administration Console by setting the following Jersey 2.x/JAX-RS application property to true:

jersey.config.wls.server.monitoring.extended.enabled

You can set this property programmatically in the JAX-RS application subclass code, or declaratively via Servlet init parameters specified in the web.xml as shown in the following examples.

For convenience, the property name is stored in the weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_EXTENDED_ENABLED constant field.

Example 7-6 provides an example of how you can enable monitoring for synthetic resources programmatically in a JAX-RS application by extending the JAX-RS Application class.

Example 7-6 Enable Synthetic Monitoring Programmatically by Extending the JAX-RS Application Class

@ApplicationPath("/")
public class MyApplication extends Application {
  
  public Map<String, Object> getProperties() {
    final Map<String, Object> properties = new HashMap<>();
    // Expose MBeans for extended JAX-RS resources and resource methods
    properties.put(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_EXTENDED_ENABLED, true);
  
    return properties;
  }
}

Example 7-7 provides an example of how you can enable monitoring of synthetic resources programmatically in a JAX-RS/Jersey application by extending the JAX-RS Jersey ResourceConfig class.

Example 7-7 Enable Synthetic Monitoring Programmatically by Extending the Jersey ResourceConfig Class

@ApplicationPath("/")
public class MyApplication extends ResourceConfig {
  
  public MyApplication() {
    // ...
  
    // Expose MBeans for extended JAX-RS resources and resource methods
    property(weblogic.jaxrs.server.WeblogicServerProperties.MONITORING_EXTENDED_ENABLED, true);
  }
  
  // ...
}

Example 7-8 provides an example of how you can enable monitoring of synthetic resources declaratively using Servlet init parameters specified in the web.xml.

Example 7-8 Enable Synthetic Monitoring Declaratively Using Servlet Init Parameters in web.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
  
<web-app version="2.5"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
  
   <servlet>
    <servlet-name>com.examples.MyApplication</servlet-name>
    ...
    <init-param>
      <param-name>jersey.config.wls.server.monitoring.extended.enabled</param-name>
      <param-value>true</param-value>
    </init-param>
    ...
    <load-on-startup>1</load-on-startup>
  </servlet>
  
  <servlet-mapping>
    <servlet-name>com.examples.MyApplication</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>