Expanded Request Tracing Service in Payara Micro
Published on 21 Sep 2017by Fabio Turizo
As previously reported on this blog, the Request Tracing Service was improved drastically in release 126.96.36.199 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 188.8.131.52 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
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 184.108.40.206, to configure the Request Tracing service you can use the following configuration options when starting a new Payara Micro instance:
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 220.127.116.11, 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 18.104.22.168 or use the --postbootcommandfile option to run asadmin commands against Payara Micro.