Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

WebSockets and the Birth of Stompee

DZone's Guide to

WebSockets and the Birth of Stompee

Stompee is an open source tool designed to let you view log output on the web with a little help from WebSockets. See what role it plays in your Java EE environment.

· Java Zone
Free Resource

Try Okta to add social login, MFA, and OpenID Connect support to your Java app in minutes. Create a free developer account today and never build auth again.

A while back, I decided to play a bit with WebSockets (JSR 356), but I wanted to do more than a "Hello World", so Stompee was born.

Why Stompee?
The name stompee comes from stomp + ee.
Stomp is the Afrikaans word for a wooden log and ee is for Java EE
Furthermore, stompie is the Afrikaans word for a cigarette butt, hence the logo.

Stompee allows you to view log output on the web. The idea is that you can fine-tune what you are looking for in the log output, and then only send those down to your browser. This might help in debugging issues in your system.

It's not meant to replace the log, but give you a more consumable part of the log output.

Development

You have no compile time dependency with Stompee, all you need to do is include the latest version of stompee-core as a runtime dependency in (for example) your pom.xml of your web project. That way, the stompee-core JAR ends up in your WAR file.

<dependency>
        <groupId>com.github.phillip-kruger</groupId>
        <artifactId>stompee-core</artifactId>
        <version>1.1.2</version>
        <scope>runtime</scope>
</dependency>


Default Settings

Optionally, you can set the default logger to use — and the level to set when you start the output. You do this by including a file named stompee.properties in /src/main/resources/. Example:

logger=com.github.phillipkruger.stompee.example
level=FINEST

Runtime

Stompee contains a @ServerEndpoint that allows you to establish a WebSocket connection to your server. Upon the deployment of your app, this endpoint is registered with the application server.

It contains a small web GUI written in Semantic UI and is available via your app context because, with any Servlet 3-compatible container, the JARs that are in the WEB-INF/lib directory are automatically made available as static resources. This works because anything in a META-INF/resources directory in a JAR in WEB-INF/lib is automatically exposed as a static resource (similar to how webJARs expose JavaScript and CSS resources).

So after you deploy your application, you can access the Stompee UI on /stompee.

So, let's look at http://<your.host>:<your.port>/<your.context>/stompee:


When the page loads, the JavaScript of the Stompee UI establishes a connection to the WebSocket endpoint and replies with your application name (above, it's stompee-example in the top right corner).

Stompee will present you with a dropdown of all registered loggers on your system. You can select the logger and hit Enter or click the Play button.

This will send a message containing your logger name to the server.

The server then adds a custom java.util.logging.Handler to that logger. That handler basically creates a JSON representation (using JSON Processing - JSR 374) of the java.util.logging.LogRecord and sends it to the UI.


The UI can now create a nice colorful representation with collapsible stacktraces to condense the log and sortable columns to make following a thread or finding some specific message easier.

Settings

You can now also (by clicking on the gear icon), change the log level of your chosen log.

Other options, like only showing log records that contain a stacktrace or allowing you to filter the log message, makes the log even more consumable.

The level, filter, and exception_only options actually happen in the Log Handler on the server side, making the data that gets sent to the UI more efficient.

The log will continue to stream to your browser via WebSocket until you stop or close/refresh the browser. When this happens, Stompee will restore the log level to the original level and remove the custom handler before disconnecting the WebSocket connection.

Deployment

When I wrote this, I had a microservice deployment model in mind, and that is why you include the JAR in your WAR. The assumption is that you would have one WAR per application server. In a case where you have multiple apps on your application server, you can also just deploy the stompee-standalone.war to that server. (stompee-standalone is an empty WAR containing stompee-core)

Stompee has been tested with the following Java EE 7 application servers:

All code is open sourced and available in GitHub. Artefacts are published to Nexus OSS and are available in Maven Central.

Build and launch faster with Okta’s user management API. Register today for the free forever developer edition!

Topics:
java ,java ee ,websockets ,stompee ,logging ,tutorial

Published at DZone with permission of Phillip Kruger. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}