Visit Azul.com Support

Request Tracing in Payara Micro

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

The Request Tracing service works the same on Payara Micro and will trace the same events described in its documentation.

Usage

Payara Micro exposes a number of command line options to configure request tracing. These options cover the most frequent use cases for Payara Micro, but you can also configure the Request Tracing Service using a post-boot command file, giving you access to the asadmin commands and the full range of options they provide.

Configuration Options

Parameter Summary

enableRequestTracing

Enables the service when present.

A supplementary parameter can be provided with this option to encapsulate the value and unit options, for example, the following will enable the service with a threshold of 4ms:

 
java -jar payara-micro.jar --enableRequestTracing 4ms

requestTracingThresholdUnit

Accepts a String value determining the time unit, defaulting to seconds if no value is given. The accepted strings are (case-insensitive):

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

This is combined with the requestTracingThresholdValue setting to determine the threshold time period.

requestTracingThresholdValue

Accepts an integer value to determine the threshold value before a request is traced, defaulting to 30 if no value is entered. This is combined with the requestTracingThresholdUnit setting to determine the threshold time period.

enablerequesttracingadaptivesampling

Enables the Adaptive Sampling option when present. When enabled, this allows the sample rate to change to attempt to meet a target count of traces over a specified period of time.

requesttracingadaptivesamplingtargetcount

Accepts an integer value to determine the threshold value before a request is traced, defaulting to 6 if no value is entered. Only used if adaptive sampling is enabled.

requesttracingadaptivesamplingtimevalue

Accepts an integer value to determine the threshold value before a request is traced, defaulting to 1 if no value is entered. Only used if adaptive sampling is enabled. This is combined with the requesttracingadaptivesamplingtimeunit setting to determine the adaptive sampling time period.

requesttracingadaptivesamplingtimeunit

Accepts a String value determining the time unit, defaulting to minutes if no value is given. The accepted strings are (case-insensitive):

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

This is combined with the requesttracingadaptivesamplingtimevalue setting to determine the adaptive sampling time period. Only used if adaptive sampling is enabled.

Shorthand Notation

To enable and configure request tracing with a single command, the --enableRequestTracing option allows you to provide one string following it to set the threshold unit and/or value.

In other words, the value and unit need to be a single string with no spaces, so 500ms would be allowed, but 500 ms would not. In the second case, the unit is ignored and the default SECONDS is kept.

Notation for units is as follows:

Unit Acceptable notation

NANOSECONDS

  • Nanoseconds (case-insensitive)

  • Nanosecond (case-insensitive)

  • ns

MICROSECONDS

  • Microseconds (case-insensitive)

  • Microsecond (case-insensitive)

  • us

  • μs

MILLISECONDS

  • Milliseconds (case-insensitive)

  • Millisecond (case-insensitive)

  • ms

SECONDS

  • Seconds (case-insensitive)

  • Second (case-insensitive)

  • s

MINUTES

  • Minutes (case-insensitive)

  • Minute (case-insensitive)

  • Mins (case-insensitive)

  • Min (case-insensitive)

  • m

HOURS

  • Hours (case-insensitive)

  • Hour (case-insensitive)

  • h

DAYS

  • Days (case-insensitive)

  • Day (case-insensitive)

  • d

Example Usages

*java -jar payara-micro.jar --enableRequestTracing: Enable request tracing **java -jar payara-micro.jar --enableRequestTracing ns: Enable request tracing and set threshold unit to nanoseconds (value defaults to 30) **java -jar payara-micro.jar --enableRequestTracing 2: Enable request tracing and set threshold value to 2 (unit defaults to SECONDS) **java -jar payara-micro.jar --enableRequestTracing 4ms*: Enable request tracing and set threshold to 4 microseconds

Warning

Exercise caution when using the shorthand notation together with other parameters. Due to the way the parser works, the last parameter entered will override the previous. For example:

 
java -jar payara-micro.jar --requestTracingThresholdUnit DAYS --enableRequestTracing 1ns

Will enable request tracing, and set the threshold to 1 NANOSECOND, while

 
java -jar payara-micro.jar --enableRequestTracing 1ns --requestTracingThresholdUnit DAYS

Will enable request tracing, and set the threshold to 1 Day