Integrating RESTEasy Tracing Feature Into WildFly

[liweinan]

Currently resteasy-tracing has two parts: API/SPI and its Implementation. The first part is located inside resteasy main repository:

• resteasy/resteasy-core/src/main/java/org/jboss/resteasy/tracing at main · resteasy/resteasy · GitHub

The second part is in the resteasy-extension repository:

• resteasy/resteasy-core/src/main/java/org/jboss/resteasy/tracing at main · resteasy/resteasy · GitHub

Currently we already have Galleon Feature Pack for the first part:

• resteasy/galleon-feature-pack/src/main/resources/modules/system/layers/base/org/jboss/resteasy/resteasy-tracing-api/main at main · resteasy/resteasy · GitHub

With the above Galleon Feature Pack, users can install the modules into WildFly dynamically with galleon.sh command line tool.

However, merely installing the module won’t enable the Tracing Feature for WildFly/EAP, because the Implementation part is not installed into WildFly/EAP yet.

Currently the loading process of resteasy-tracing is located here:

• resteasy/RESTEasyTracingLogger.java at main · resteasy/resteasy · GitHub

As shown in the above code, the RESTEasyTracingLogger will try to find a implementation of the RESTEasyTracing abstract class from current classpath:

public interface RESTEasyTracingLogger
{
   class TRACING {
      public static final boolean AVAILABLE;
      static {
         boolean b;
         try {
Class.forName("org.jboss.resteasy.tracing.api.RESTEasyTracing");
            b = true;
         } catch (Throwable t) {
            b = false;
         }
         AVAILABLE = b;
      }
   }

And the above org.jboss.resteasy.tracing.api.RESTEasyTracing abstract class is located in the resteasy-extension subproject:

• resteasy-extensions/RESTEasyTracing.java at main · resteasy/resteasy-extensions · GitHub

So the tracing feature loading logic is:

• If there is org.jboss.resteasy.tracing.api.RESTEasyTracing in the classpath(which means resteasy-extensions is added into project dependency scope), then the tracing feature will be enabled, otherwise the tracing feature is bypassed.

To summarize the above analyze process, here is the class diagram of the tracing feature in resteasy-extension:

And here is the class diagram of the tracing feature core classes that combining the resteasy and resteasy-extension:

In conclusion, if we want to enable the tracing feature inside WildFly/EAP, then we need to make resteasy-extension as feature pack too, so WildFly/EAP can use it internally.

In addition, if we want to expose the tracing feature from WildFly/EAP to the deployed projects, we need to write a processor like *JaxrsSpringProcessor:

• wildfly/JaxrsSpringProcessor.java at main · wildfly/wildfly · GitHub

If we don’t write a processor like this, then the tracing module can only be used by WildFly/EAP by itself.

Nevertheless, the deployed project can add resteasy-extensions into their own project dependency scope and bundle it themselves. Here is an example using the tracing feature:

• resteasy-examples/tracing-example at main · resteasy/resteasy-examples · GitHub

Tracing Mode

The tracing feature can set it’s working mode at runtime, and there are three modes defined in ResteasyContextParameters:

/**
 * Enable tracing support.
 * <p>
 * It allows service developer to get diagnostic information about request processing by RESTEasy.
 * Those diagnostic/tracing information are returned in response headers ({@code X-RESTEasy-Tracing-nnn}).
 * The feature should not be switched on on production environment.
 * <p>
 * Allowed values:
 * <ul>
 * <li>{@code OFF} - tracing support is disabled.</li>
 * <li>{@code ON_DEMAND} - tracing support is in 'stand by' mode, it is enabled on demand by existence of request HTTP header</li>
 * <li>{@code ALL} - tracing support is enabled for every request.</li>
 * </ul>
 * Type of the property value is {@code String}. The default value is {@code "OFF"}.
 * <p>
 * The name of the configuration property is <code>{@value}</code>.
 * </p>
 */
String RESTEASY_TRACING_TYPE = "resteasy.server.tracing.type";
String RESTEASY_TRACING_TYPE_OFF = "OFF";
String RESTEASY_TRACING_TYPE_ALL = "ALL";
String RESTEASY_TRACING_TYPE_ON_DEMAND = "ON_DEMAND";

The default mode is OFF, so the tracing feature won’t output any tracing information, and if we integrate the tracing feature into WildFly/EAP, then WildFly/EAP can use the mode setting internally to modify the tracing mode. For deployed projects, these parameters can be set runtime too(I need to provide an example how to do this).

To summarize the above report, there are several things we need to decide:

• Should we provide the tracing feature into WildFly/EAP as a jboss-module or galleon-feature-pack.
• Should we provide a processor inside WildFly/EAPfor the tracing feature, so the deployed project can use it directly without adding the resteasy-extensions into their own project dependency scope.
• How should WildFly/EAP use the tracing feature(for example, how should the server set the tracing mode internally).
• How should the deployed project use the tracing feature(setting tracing modes, etc).

[jamezp]

Hi @liweinan. Excellent analysis!

A couple things I see when looking at this.

1. I think we need to change the API a bit. I'd need to do some further analysis, but there is a lot of static fields that might not work well for multi-tenant environments.
2. IMO we don't want a DUP like JaxrsSpringProcessor. We need a way to add an attribute to the subsystem which would indicate whether or not the dependency should be added. Then when the dependency is present things should just work.

In general I've got no opposition to having inside WildFly. However, I see this as more of a debug feature. I don't think using this in production would be advisable as it would impact performance.

[liweinan]

@jamezp Thanks for reviewing! And Looking forward to some more analysis :D

Meanwhile I'll keep sharing my thought/code here.