WebSphere Application Server & Liberty

As part of building some educational labs, our team has created a new diagnostic application for WebSphere Liberty called libertydiag. This application may be used to perform diagnostics such as requesting thread dumps and core dumps, generating artificial HTTP load, sleeping an application request for a long time, and other utilities. This blog post will explore libertydiag and how you can run it locally, as a .war file, and/or in Kubernetes/OpenShift.

libertydiag

libertydiag is an Eclipse MicroProfile 5 and Jakarta EE 9 (Web Profile) web application for simulating diagnostic situations. Its source is available at https://github.com/IBM/libertydiag with the Apache 2.0 license. The application is not supported by IBM and is provided on an "as-is" basis without warranty of any kind; however, we will do our best as time permits to resolve issues opened on the GitHub Issue tracker.

The application exposes various HTTP endpoints and here are some highlights:

1. /servlet/Sleep: Sleeps the executing Servlet thread for a specified duration
2. loadrunner.jsp : Generate concurrent user traffic for an HTTP endpoint
3. /servlet/ThreadDump: Request a thread dump on J9-based JVMs
4. /servlet/HeapDump: Request a heap dump on J9-based JVMs
5. /servlet/SystemDump: Request a core dump (with request=exclusive+prepwalk) on J9-based JVMs
6. /servlet/GarbageCollect: Call java.lang.System.gc()
7. /servlet/AllocateObject: Allocate an arbitrary amount of Java heap (e.g. to simulate OOMs)
8. /servlet/Hang: Hangs the servlet thread infinitely
9. /servlet/Deadlocker: Attempt to create a deadlock with an algorithm that emulates the Dining Philosophers problem
10. /servlet/DoComplicatedStuff: Generate various CPU usage such as compiling regular expressions, creating BigDecimals, creating long Strings, and calculating PI.
11. /servlet/InfiniteLoop: loops infinitely on a servlet thread in a while loop with some trivial math operations
12. /servlet/SystemExit: Calls Runtime.halt()
13. /servlet/Exceptions: Test throwing exceptions
14. /servlet/AllocateNativeMemory: Allocates a certain amount of native memory
15. /servlet/ClassloaderLeakMemory: Spawns a thread so that when the application is stopped, the application classloader will not be able to be cleaned up (i.e. it will be "leaked").
16. /servlet/LargeResponse: Serve a large HTTP response payload
17. /health: MicroProfile Health JSON endpoint
18. /metrics: MicroProfile Metrics Prometheus-style metrics output
19. /api/helloworld/execute: Simple Hello World JSON REST API
20. /servlet/HelloWorldServlet: Simple Hello World Servlet

As you can see with servlets such as InfiniteLoop and SystemExit, running this application in production should be done with care because it may be used to execute various powerful functions.

Running libertydiag

There are three main ways to run the application:

1. Download libertydiag.war from the latest release on GitHub: https://github.com/IBM/libertydiag/releases/latest
   
   1. Then install it into an existing Liberty server, ensuring the feature manager includes: <feature>webProfile-9.1</feature> and <feature>microProfile-5.0</feature>
   2. Note that this requires Liberty >= 22.0.0.1
2. Run the container image quay.io/ibm/libertydiag available from RedHat's Quay.io: https://quay.io/repository/ibm/libertydiag
3. Build it from source by cloning the repository and running ./mvnw clean liberty:dev (macOS and Linux) or mvnw clean liberty:dev (Windows)

Running libertydiag.war

If you have an existing Liberty server you'd like to add the application to, one common way to do it would be to just copy it into the dropins folder.

First, ensure server.xml includes the required features:

  <featureManager>
    <feature>webProfile-9.1</feature>
    <feature>microProfile-5.0</feature>
  </featureManager>

Next, download libertydiag.war from https://github.com/IBM/libertydiag/releases/latest into the dropins folder.

If the server is already started, it should pick it up; otherwise, start the server.

The application should be available at /libertydiag/

Deploying to Kubernetes/OpenShift

If you'd like to deploy to Kubernetes/OpenShift, first create a YAML file pointing to the image; for example:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: libertydiag
  labels:
    app: libertydiag
spec:
  selector:
    matchLabels:
      app: libertydiag
  template:
    metadata:
      labels:
        app: libertydiag
    spec:
      containers:
      - name: libertydiag
        image: quay.io/ibm/libertydiag
        imagePullPolicy: Always
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 9080
            scheme: HTTP
          initialDelaySeconds: 1
          periodSeconds: 10
          timeoutSeconds: 3
          failureThreshold: 1​

Then deploy the YAML file:

oc apply -f libertydiag.yaml​

Run the following command which will wait until the deployment is ready:

oc wait deployment libertydiag --for condition=available --timeout=5m​

Create a service for the application to create a load balancer to the deployment:

oc expose deployment libertydiag --port=80 --target-port=9080​

Create a route for the application to expose the service externally:

oc create route edge --service=libertydiag​

List the route's URL:

oc get route libertydiag "--output=jsonpath={'https://'}{.spec.host}{'/\n'}"​

Access the resulting URL.

Summary

In conclusion, the new libertydiag application provides various diagnostic capabilities for educational purposes or for simulating conditions within a Liberty JVM or Kubernetes/OpenShift environment.

#automation-portfolio-specialists-app-platform
​#WebSphere#WebSphereLiberty#OpenLiberty​​​