This chapter describes how 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).
This chapter includes the following sections:
Monitoring RESTful Web Services Using Enterprise Manager Fusion Middleware Control
Monitoring RESTful Web Services Using the Administration Console
Enable Monitoring of Synthetic Jersey Resources in a RESTful Web Service Application
WebLogic Server provides several run-time MBeans that capture run-time information and let you monitor run-time statistics for your RESTful web service applications. Application monitoring is useful when you need to identify the performance hot-spots 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 run-time information and monitor run-time statistics, as described in Monitoring RESTful Web Services Using Enterprise Manager Fusion Middleware Control. |
|
WebLogic Server Administration Console |
Access run-time information and monitor run-time statistics, as described in Monitoring RESTful Web Services Using the Administration Console. |
|
WebLogic Scripting Tool (WLST) |
Access run-time information and monitor run-time 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. For more information, see "Monitoring Jersey Applications" in the Jersey 2.21 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. For more information, see "Disabling RESTful Web Service Application Monitoring".Using Enterprise Manager Fusion Middleware Control, you can monitor run-time 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.
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:
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).
Follow the procedure described in "Monitor RESTful Web Services" in Oracle WebLogic Server Administration Console Online Help.
You can use WLST to monitor the run-time MBeans, defined in Table 7-2, that capture run-time information and run-time statistics for your RESTful web service applications.
Table 7-2 Run-time MBeans for Monitoring RESTful Web Services
| Run-time MBean | Description |
|---|---|
|
|
Displays monitoring information about the RESTful web service application exception mapper executions. For more information, see "JaxRsExceptionMapperStatisticsRuntimeMBean" in MBean Reference for Oracle WebLogic Server. |
|
|
Displays monitoring information for the RESTful web service application. For more information, see "JaxRsApplicationRuntimeBean" in the MBean Reference for Oracle WebLogic Server. |
|
|
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. For more information, see "JaxRsExecutionStatisticsRuntimeMBean" in MBean Reference for Oracle WebLogic Server |
|
|
Displays monitoring information about the RESTful web service application resource configuration. For more information, see "JaxRsResourceConfigTypeRuntimeBean" in the MBean Reference for Oracle WebLogic Server. Note: The |
|
|
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. For more information, see "JaxRsResponseStatisticsRuntimeMBean" in MBean Reference for Oracle WebLogic Server. |
|
|
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. For more information, see "JaxRsResourceRuntimeMBean" in the MBean Reference for Oracle WebLogic Server. Note: This MBean is deprecated in this release of WebLogic Server. You should use |
|
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. For more information, see "JaxRsResourceRuntimeMBean" in the MBean Reference for Oracle WebLogic Server. |
|
|
|
Displays monitoring information for each URI that is exposed in the RESTful web service application. For more information, see "JaxRsUriRuntimeMBean" in MBean Reference for Oracle WebLogic Server. |
|
|
Displays monitoring information for the servlet that hosts the RESTful web service application. For more information, see "ServletRuntimeMBean" in the 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
Invoke WLST, as described in "Invoking WLST" in Understanding the WebLogic Scripting Tool.
For example:
c:\Oracle\oracle_common\common\bin> wlst
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')
Navigate to the server run-time 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>
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')
Navigate to the application run-time 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')
Review the monitoring information displayed for the RESTful web service application. For more information, see "JaxRsApplicationRuntimeBean" in the 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>
Navigate to any of the other run-time MBeans described in Table 7-2 to view additional monitoring information.
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:\>
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.21 User Guide.
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:
At the application level, you can set a WebLogic Server-specific Jersey 2.x application property, jersey.config.wls.server.monitoring.enabled. For more information, see "Disabling Monitoring for a RESTful Web Service Application Using Jersey Property".
At both the application level and at the domain level, you can disable monitoring using a WebLogic Configuration MBean, WebAppComponentMBean.JaxRsMonitoringDefaultBehavior. For more information, see "Disabling Monitoring for a RESTful Web Service Application Using WebLogic Configuration MBean" and "Disabling RESTful Web Service Application Monitoring for a WebLogic Domain"
WebLogic Server uses the following algorithm to determine whether monitoring should be enabled or disabled for each application.
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.
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.
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.
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.
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>
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.
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. For more information, 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 theconfig.xml file directly. For more information, see "Domain Configuration Files" in Understanding Domain Configuration for Oracle WebLogic ServerWhen 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>