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.
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>
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:
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
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:
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.
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.
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: