The monitor-1.0 feature in WebSphere Liberty provides performance metrics such as database connection pool size, servlet response time, JVM garbage collection time, and so on. You can use this to understand how your Java application performs on a Liberty server, and administrators can monitor and tune the performance of your application in production.

Some background

Traditional WebSphere Application Server (WAS) has long provided a number of performance indicators, or counters, or metrics, as part of the Performance Monitoring Infrastructure (PMI). For example, PMI provides metrics for database connection pool size, servlet response time, Enterprise JavaBeans (EJB) method response time, Java virtual machine (JVM) garbage collection time, CPU usage, and others. This data can be used to understand the runtime resource utilization patterns of the thread pool, connection pool, and so on, and the performance characteristics of the application components like servlets, JavaServer Pages (JSP), and enterprise beans. These metrics and counters can be used to monitor the health of the application server and to tune the performance of applications. Typically, tools gather the values of the desired counters and display those values in some sort of a user interface. For traditional WAS, most tools gather these metrics through JMX MBeans.

Because of the usefulness of these metrics, Liberty provides similar performance monitoring metrics as part of the monitor-1.0 feature. To find out more about monitoring Liberty servers in general, see the Knowledge Center docs.

Like traditional WAS, Liberty users can either use tools to visualize these metrics, or directly obtain the metrics themselves by invoking the appropriate MBean through JMX. To find out more, see the Knowledge Center docs. Unlike traditional WAS, Liberty also allows users (and tools) to obtain these metrics using RESTful interfaces as described in a Accessing Liberty’s JMX REST APIs.

Why bring this up now?

The set of metrics provided by Liberty is similar to, but not exactly the same as, the set provided by traditional WAS. The monitor-1.0 feature has been around for a while but, as part of the Liberty release, we addressed a Request For Enhancement (RFE) asking us to provide an additional metric for the ConnectionPoolStats MBean in Liberty that was in traditional WAS. We do listen to your requests and try to address some of them with each release.

As part of that work, I wanted to take the opportunity to explain how you might start taking advantage of monitoring for Liberty. I’ll use the new Liberty metric, InUseTime, as an example. This metric is one of a set of metrics of the ConnectionPoolStats MBean related to JDBC and JCA connection pooling. To find out more about monitoring of Liberty connection pools, see the Knowledge Center docs.

What’s new?

Traditional WAS provides a JDBC connection pool counter named UseTime, which is the average time in milliseconds that a JDBC connection is in use. As part of our on-going effort to ease migration between the two application servers, and in response to the RFE I mentioned earlier, we’ve added a similar counter named InUseTime to the set of Liberty monitoring metrics.

The name was changed in Liberty to better reflect the usage of the counter. The InUseTime and UseTime metrics are useful in understanding how quickly (or slowly) database connections are being obtained, used, and returned to the connection pool. Typically, a lower number is better and indicates that applications shouldn’t have to wait very long to obtain a connection from the connection pool. Using this new metric in conjunction with the other metrics gives a more complete view of the overall health of database connections of the app server.

So, how to access this info? First, you’ll need to add the restConnector-2.0 and monitor-1.0 features to your Liberty server.xml. If the monitor feature is not installed on your app server, you can install it by using the command bin/installUtility install monitor-1.0 from your Liberty runtime directory. You’ll also need some sort of application that accesses a database and thus creates a connection pool for the associated data source. This is necessary because connection pools are lazy by nature and are only created when needed. Once you’ve enabled the features listed above and an application is running, you can access the REST interface to the JDBC/JCA connection pool MBean. For simplicity, I’m going to use a browser to access the REST interfaces. You can do the same or you can use any other REST client.

wRESTing Metrics from the Connection Pool

First, let’s find the URL for the connection pool MBean by listing all of the registered MBeans using this URL:

The response is a JSON object that lists all registered MBeans and, if we search that list for ConnectionPoolStats (the object name of the MBean), we’ll find a JSON object like this:


If you’re running multiple JDBC applications that access multiple data sources, your JSON response to the query contains multiple objects, one per connection pool or data source. If so, simply search those results for the JNDI name of your datasource. For this example, my application uses a data source with a JNDI name of jdbc/DictionaryDB. The JSON object for your connection pool lists the URL of the REST interface for the connection pool metrics, ConnectionPoolStats. In my example, the URL is https://localhost:9443/IBMJMXConnectorREST/mbeans/WebSphere%3Aname%3Djdbc%2FDictionaryDB%2Ctype%3DConnectionPoolStats

The JSON response from that URL gives us a list of fetchable attributes and, since we’re talking about InUseTime, let’s grab that one from the URL attribute: URL:/IBMJMXConnectorREST/mbeans/WebSphere%3Aname%3Djdbc%2FDictionaryDB%2Ctype%3DConnectionPoolStats/attributes/InUseTime

Visiting that URL yields a JSON response that looks something like this:


So, for my sample application, connections from the pool were in use for 355 milliseconds. Of course, although it’s useful to test drive the REST API from the browser, it’s likely more useful to either use one of the many tools to obtain the metrics, or write a client that can access the REST interfaces and understand the JSON responses.

Apples and oranges

As I mentioned earlier, traditional WAS and Liberty share some of the same metrics. Some of them have the same name; some are slightly different. The table below compares the set of ConnectionPoolStats MXBean metrics to that of traditional. To make things easier, for those that are common, even if the name is slightly different, the interpretation of the contents is the same. There are additional metrics in traditional WAS that are not present in Liberty but, in some cases, the metric can calculated from other existing metrics. For example, traditional WAS has a metric, PoolSize, that is not in Liberty but a Liberty user can calculate the value through simple subtraction:

pool size = ManagedConnectionCount – FreeConnectionCount

Comparison of ConnectionPoolStats MXBean metrics
Traditional WAS metric name Liberty metric name Description
CreateCount CreateCount The total number of managed connections that have been created since pool creation.
CloseCount DestroyCount The total number of managed connections that have been destroyed since pool creation.
ManagedConnectionCount ManagedConnectionCount The total number of managed connections in the free, shared, and unshared pools.
WaitTime WaitTime The average waiting time in milliseconds until a connection is granted if a connection is not currently available.
ConnectionHandleCount ConnectionHandleCount The number of connections that are in use. This number might include multiple connections that are shared from a single managed connection.
FreePoolSize FreeConnectionCount The number of managed connections in the free pool.
UseTime InUseTime The average time in milliseconds that a connection is in use.


Using the newly added InUseTime metric of the ConnectionPoolStats MXBean as an example, we’ve looked at how to retrieve metrics from the Liberty server using the REST interface. We’ve also compared the available set of metrics between traditional WAS and Liberty app servers and discussed some of the differences. Hopefully this information will useful in helping you better understand Liberty connection pooling metrics.

Related articles

1 comment on"How to tell if your app server is sick (new in"

  1. […] users transitioning from traditional WAS to Liberty because it provides similar functionality. See How to tell if your app server is sick (new in for more […]

Join The Discussion

Your email address will not be published. Required fields are marked *