Chapter 12. Monitoring your application

This section contains information about monitoring your Thorntail–based application running on OpenShift.

12.1. Accessing JVM metrics for your application on OpenShift

12.1.1. Accessing JVM metrics using Jolokia on OpenShift

Jolokia is a built-in lightweight solution for accessing JMX (Java Management Extension) metrics over HTTP on OpenShift. Jolokia allows you to access CPU, storage, and memory usage data collected by JMX over an HTTP bridge. Jolokia uses a REST interface and JSON-formatted message payloads. It is suitable for monitoring cloud applications thanks to its comparably high speed and low resource requirements.

For Java-based applications, the OpenShift Web console provides the integrated hawt.io console that collects and displays all relevant metrics output by the JVM running your application.

Prerequistes

  • the oc client authenticated
  • a Java-based application container running in a project on OpenShift
  • latest JDK 1.8.0 image

Procedure

  1. List the deployment configurations of the pods inside your project and select the one that corresponds to your application. 

    oc get dc
    NAME         REVISION   DESIRED   CURRENT   TRIGGERED BY
MY_APP_NAME   2          1         1         config,image(my-app:6)
...

  2. Open the YAML deployment template of the pod running your application for editing. 

    oc edit dc/MY_APP_NAME

  3. Add the following entry to the ports section of the template and save your changes: 

    ...
spec:
  ...
  ports:
  - containerPort: 8778
    name: jolokia
    protocol: TCP
  ...
...

  4. Redeploy the pod running your application. 

    oc rollout latest dc/MY_APP_NAME

    The pod is redeployed with the updated deployment configuration and exposes the port 8778.

  5. Log into the OpenShift Web console.
  6. In the sidebar, navigate to Applications > Pods, and click on the name of the pod running your application.
  7. In the pod details screen, click Open Java Console to access the hawt.io console.

Additional resources

12.2. Application metrics

Thorntail provides ways of exposing application metrics in order to track performance and service availability.

12.2.1. What are metrics

In the microservices architecture, where multiple services are invoked in order to serve a single user request, diagnosing performance issues or reacting to service outages might be hard. To make solving problems easier, applications must expose machine-readable data about their behavior, such as:

  • How many requests are currently being processed.
  • How many connections to the database are currently in use.
  • How long service invocations take.

These kinds of data are referred to as metrics. Collecting metrics, visualizing them, setting alerts, discovering trends, etc. are very important to keep a service healthy.

Thorntail provides a fraction for Eclipse MicroProfile Metrics, an easy-to-use API for exposing metrics. Among other formats, it supports exporting data in the native format of Prometheus, a popular monitoring solution. Inside the application, you need nothing except this fraction. Outside of the application, Prometheus typically runs.

Additional resources

12.2.2. Exposing application metrics

In this example, you:

  • Configure your application to expose metrics.
  • Collect and view the data using Prometheus.

Note that Prometheus actively connects to a monitored application to collect data; the application does not actively send metrics to a server.

Prerequisites

  • Prometheus configured to collect metrics from the application:

    1. Download and extract the archive with the latest Prometheus release: 

      $ wget https://github.com/prometheus/prometheus/releases/download/v2.4.3/prometheus-2.4.3.linux-amd64.tar.gz
$ tar -xvf  prometheus-2.4.3.linux-amd64.tar.gz

    2. Navigate to the directory with Prometheus: 

      $ cd  prometheus-2.4.3.linux-amd64

    3. Append the following snippet to the prometheus.yml file to make Prometheus automatically collect metrics from your application: 

        - job_name: 'thorntail'
    static_configs:
    - targets: ['localhost:8080']

      The default behavior of Thorntail-based applications is to expose metrics at the /metrics endpoint. This is what the MicroProfile Metrics specification requires, and also what Prometheus expects.

  • The Prometheus server started on localhost:

    Start Prometheus and wait until the Server is ready to receive web requests message is displayed in the console. 

    $ ./prometheus

Procedure

  1. Include the microprofile-metrics fraction in the pom.xml file in your application:

    pom.xml

    <dependencies>
  <dependency>
    <groupId>io.thorntail</groupId>
    <artifactId>microprofile-metrics</artifactId>
  </dependency>
</dependencies>

  2. Annotate methods or classes with the metrics annotations, for example: 

    @GET
@Counted(name = "hello-count", absolute = true)
@Timed(name = "hello-time", absolute = true)
public String get() {
    return "Hello from counted and timed endpoint";
}

    Here, the @Counted annotation is used to keep track of how many times this method was invoked. The @Timed annotation is used to keep track of how long the invocations took.

    In this example, a JAX-RS resource method was annotated directly, but you can annotate any CDI bean in your application as well.

  3. Launch your application: 

    $ mvn thorntail:run

  4. Invoke the traced endpoint several times: 

    $ curl http://localhost:8080/
Hello from counted and timed endpoint

  5. Wait at least 15 seconds for the collection to happen, and see the metrics in Prometheus UI:

    1. Open the Prometheus UI at http://localhost:9090/ and type hello into the Expression box.
    2. From the suggestions, select for example application:hello_count and click Execute.
    3. In the table that is displayed, you can see how many times the resource method was invoked.
    4. Alternatively, select application:hello_time_mean_seconds to see the mean time of all the invocations.

    Note that all metrics you created are prefixed with application:. There are other metrics, automatically exposed by Thorntail as the MicroProfile Metrics specification requires. Those metrics are prefixed with base: and vendor: and expose information about the JVM in which the application runs.

Additional resources