Expanded Request Tracing Service in Payara Micro

Photo of Fabio Turizo by Fabio Turizo

As previously reported on this blog, the Request Tracing Service was improved drastically in release and implemented the configuration of a historic trace record storing for increased productivity purposes. In addition to these changes, we also made the configuration on the Request Tracing Service in Payara Micro for the same release. These changes to Payara Micro make it simpler to configure the Request Tracing Service when starting a new instance!


Using Request Tracing in Payara Micro 164

Prior to release in order to make configuration changes to the Request Tracing Service, you had to implement them by using either one of the following two options:


1. Configure the Request Tracing service using a custom domain.xml

For example, let's say you want to configure an instance that runs the Request Tracing service every 2 minutes, you would have the following XML excerpt in a valid domain.xml called (in this example) reqtrace-config-domain.xml:

<request-tracing-service-configuration enabled="true" threshold-unit="MINUTES" threshold-value="2"></request-tracing-service-configuration>

Then, you would start a new instance by running the following command:

java -jar payara-micro.jar --domainConfig=./reqtrace-config-domain.xml

A possible alternative would be to use the --rootDir option and edit the packaged domain.xml.


2. Configure the Request Tracing service programmatically using the PayaraMicroRuntime.run method

For example, let's say you want to configure an instance that runs the Request Tracing service with a threshold of 300 milliseconds. You would need to create a simple Java class that prepares and runs an instance of Payara Micro by passing the correct arguments to the requesttracing-configure asadmin command, like this:


PayaraMicro.getInstance().bootstrap().run("requesttracing-configure", "--enabled=true", "--dynamic=true", "--thresholdValue=300", "--thresholdUnit=MILLISECONDS");



Native Command-Line Options

Needless to say, both ways to configure the service are cumbersome. Starting from release, to configure the Request Tracing service you can use the following configuration options when starting a new Payara Micro instance:

  • enableRequestTracing

  • requestTracingThresholdUnit
  • requestTracingThresholdValue

The first option, enableRequestTracing; enables the request tracing service. If this is the only configuration option present when starting a new Micro instance, then the service will be configured to be executed every 30 seconds (which is the default configuration), like this:


java -jar payara-micro.jar --enableRequestTracing


 The other two options allow configuration of the time threshold after which a request will be traced. The requestTracingThresholdUnit defines the unit of time for this threshold, having any valid java.util.concurrent.TimeUnit string as its possible value. The requestTracingThresholdValue defines the amount of time units used to configure the threshold. To configure the service to log any request which takes longer than 2 minutes for a new instance, run the following command:


java -jar payara-micro.jar --enableRequestTracing --requestTracingThresholdUnit 2 requestTracingThresholdUnit MINUTES


If either one of these two options are missing, then the default values apply (SECONDS and 30 as mentioned before).

To make the configuration more intuitive, the enableRequestTracing can be succeeded with a "short notation" string that defines the threshold for the service by concatenating the value and the time unit together. The previous command can then be shortened like this:


java -jar payara-micro.jar --enableRequestTracing 2MINUTES


This simplifies the configuration and makes the command shorter and easier to understand. This shorthand notation even accepts abbreviations for the time unit too. MINUTES can be shortened to 'm', making the command even shorter:


java -jar payara-micro.jar --enableRequestTracing 2m


The shorthand notation makes extremely easy to configure the Request Tracing service. If you want to know what is the valid list of abbreviations for each of the time units, check the official documentation.



Keep in mind that if you both use the shorthand notation and the requestTracingThreshold- options, Payara Micro will prioritize the last parameters entered from left to right. So, for example, the following command:


java -jar payara-micro.jar --enableRequestTracing 2ms requestTracingThresholdUnit NANOSECONDS


Will configure the frequency of the service's execution to 2 nanoseconds instead of 2 milliseconds, since the last option set the time unit to nanoseconds.


(!) Missing configuration options (!)

As of release, the Request Tracing Service can be configured to enable or disable the list of active notifiers to use when tracing events are generated. Currently, there are no configuration options to enable active notifiers for the Request Tracing Service on Payara Micro. When enabling the service, only the Log Notifier, which is the the default notifier, will be enabled. In the case you want to configure other notifiers, you will have to rely on the methods described for release or use the --postbootcommandfile option to run asadmin commands against Payara Micro.



   Payara Micro        find out more