Introducing Vertx Subsystem in WildFly Preview

By | December 17, 2024

I’m excited to announce the integration of the WildFly Vertx Feature Pack into WildFly Preview from WildFly 35 Beta release. This feature pack introduces Vertx configuration capabilities through the WildFly management model, making it easier to manage and integrate Vertx with existing WildFly subsystems.

Note	In the 35 release, the vertx subsystem is only available in WildFly Preview, and not in standard WildFly. It is provided at the `preview` stability level, which is enabled out-of-the-box in WildFly Preview.

Eclipse Vert.x Overview

Eclipse Vert.x is an open-source toolkit designed for building event-driven, asynchronous applications.

Currently, Vertx instances have been used by opentelemetry and microprofile-reactive-messaging-smallrye subsystems within WildFly to provide features powered by vertx components underneath, but there was no central mechanism to configure them.

Key Features of the WildFly Vertx Feature Pack

This feature pack provides centralized configuration and management of the Vertx instance, so administrators now have a unified way to define and manage the Vertx instance.

Following the recommendation from the Vert.x team, it is good to have a single Vertx instance for everything, which ensures optimal efficiency and simplicity.

Configurable VertxOptions: Administrators can define Vertx configurations using the WildFly management model, ensuring consistency across subsystems.
Expose the Vertx Instance to CDI container: When administrators set up a Vertx instance in the vertx subsystem, it is exposed to the CDI container with a fixed qualifier, so other subsystems like opentelemetry and microprofile-reactive-messaging-smallrye can use it using CDI API.

Configuring Vertx instance in WildFly Preview

Vertx instance in WildFly Preview is configured using the new vertx subsystem. This subsystem isn’t included in any of WildFly Preview’s out-of-the-box configuration files, so to use it you’ll need to add it to your configuration.

If you’re using a complete WildFly Preview installation, like the ones available from the WildFly downloads page, then you can use the JBoss CLI to add the vertx extension and subsystem to your configuration:

$ /extension=org.wildfly.extension.vertx:add
$ /subsystem=vertx:add

Once vertx subsystem is added, you can define some VertxOptions and set up the Vertx instance to refer to the options you just configured:

$ /subsystem=vertx/vertx-option=vo:add(event-loop-pool-size=20, max-eventloop-execute-time=5, max-eventloop-execute-time-unit=SECONDS)
$ /subsystem=vertx/vertx=vertx:add(option-name=vo)

You will see the configuration like:

standalone.xml

<subsystem xmlns="urn:wildfly:vertx:preview:1.0">
    <vertx option-name="vo"/>
    <vertx-options>
        <vertx-option name="vo" event-loop-pool-size="20" max-eventloop-execute-time="5" max-eventloop-execute-time-unit="SECONDS"/>
    </vertx-options>
</subsystem>

For more configuration, please refer to the Configuration-Guide in the wildfly-vertx-feature-pack Wiki page.

Use Cases

With above configuration, there is a Vertx instance exposed in CDI container with a qualifier, which has been integrated to opentelemetry subsystem (microprofile-reactive-messaging-smallrye subsystem soon) by setting the associated configuration item internally.

So when you play opentelemetry-tracing quickstart with the vertx configuration above, you will see a log message:

[org.wildfly.extension.vertx] (default task-1) WFLYVTX0008: Use Vertx instance from vertx subsystem

which indicates that the Vertx instance from the vertx subsystem is used underneath. The Vertx instance has 20 event loop threads set, and it will log a warning if it detects that event loop threads haven’t returned within 5 seconds.

Future plan

There is a plan to increase the stability level to community and finally to the default level to be used in the standalone WildFly distributions.
Now the vertx subsystem is integrated internally whenever it is available, maybe it is better to give the decisions to the administrators so that they can configure the opentelemetry subsystem and microprofile-reactive-messaging-smallrye subsystem to use or not the vertx instance coming from the vertx subsystem.
When this vertx subsystem becomes mature enough and higher stability level, we also consider to move it to WildFly codebase to align the release cycles.

Please try out the vertx subsystem in WildFly Preview and give us your feedback! We’ll continue to work on the integration, with a goal of including it in standard WildFly in one of the next couple of releases.