Payara InSight

To switch page use the left menu.

Since version 5.20.0, each page switch also updates the URL making the URL bookmarkable. URLs can be copied and shared with others to direct them to particular pages.

Updating URLs after switching pages also means that navigation based on the browser’s page history is possible and the back button can be used to already visited pages.

Each page uses a column layout of one or more columns. The number of columns for a page can be changed using one of the Layout Columns quick access buttons.

Changing the column layout of a page does not change the preferred position of the widgets. If a widget is set to column 3 but a 2-column layout is used all widgets of the 3rd or 4th column get pushed to the 2nd column instead. This allows switching layouts based on the viewing device without redoing the configuration entirely.

By default, the graphs on a page update every 2 seconds. To control the interval use quick access in the left side menu or General application settings.

The interval can be paused and continued without changing the interval duration by using the play/pause toggle next to the interval setting.

To add a new page expand the left menu, click the Add New Page button below the list of pages and enter a name for the new page in the dialogue.

Usually pages are populated manually. Use the Add New Widgets button in the right sidebar (+ when minimized) to populate the page and configure the added widgets.

Alternatively pages can use a query to automatically populate the page with widgets for those metrics that match the query. To use a query page open the page settings and switch the Type to Query:

Fill in Query Series and Query Interval and click the Update Now button.

Learn more about series patterns as used by query pages.

To delete a page open the left sidebar and click the on the trash icon next to the page name in the list of pages you want to delete.

Confirm the deletion.

When the configuration of a preconfigured page or any of the widgets on it was changed by the user the page can be reset by clicking the Reset icon next to the page name in the expanded left side menu.

Confirm the reset.

Payara InSight is meant to be used to display metrics on status monitors. To allow viewing a variety of pages and their metrics on a single screen the pages can be automatically rotated showing each page for a configured interval duration.

To start or stop page rotation either use the quick access button at the button of the left side menu or use the toggle switch in the General application settings. This starts or stops the rotation immediately and each page is shown for the configured duration starting with the currently shown page.

The duration can be adjusted by changing the text field of the Page Rotation to another time value. Use units to express the duration, as for example: 1min, 30sec. Changes take effect immediately.

Individual pages can be excluded from rotation by toggling the Include In Rotation toggle to No in the page settings.

Payara InSight uses the browser’s local storage to store the page and widget configuration. This means that, by default, changes to page configurations do not affect other users. To make pages available to others and to start from a common base configuration pages are explicitly shared and updated from a persistent server configuration.

The chosen role controls the behaviour and available options for page management. It is the Administrator's role that is meant to manage the persistent server page configuration. The Administrator explicitly pushes local pages to the server to share and update their base configuration. Users and Guests pull the server configuration to update their local configuration with the base. The control remains with each user.

The Page Synchronisation dialogue shown when entering the GUI allows the user to pick the pages that should be updated (pulled).

By default, all pages available remotely that have not been changed locally are preselected.

The newest version is marked with an asterisk for easier orientation.

This dialogue can also be opened from the Pages application settings by clicking the Update Local…​ button for the Page Sync property.

Administrators also find a button to Update Server…​ pages with any changes applied to local changes. This is only needed for pages that are not using auto_matic updates in their page settings. This simply should give administrators different approaches to managing the configuration of shared pages. To bulk update all server pages click the _Update Server…​ button and confirm the update:

To share a page that so far is not part of the persistent server configuration open the Page settings and look for the Server Sync property.

Both Users and Administrators can Push a page to share or update the persistent server configuration or Pull the server configuration to update the local page. Administrators can also enable or disable the automatic page synchronisation. When enabled any local change done by an Administrator is automatically pushed to the remote configuration.

Both Push and Pull need to be confirmed.

Besides the managed page synchronisation which is using the persistent server configuration the local configuration can also be managed manually. To manually export pages click the Export…​ button and select the set of pages to export in the dialogue and confirm your selection by pressing Export

To manually import pages click the Import…​ button and select a file. The dialogue will show the list of pages contained in the file. Select the pages that should be imported.

A user of Payara InSight acts in one of three roles:

When no role is set from previous sessions the user is asked to choose a role when opening the Payara InSight application.

The selection can be changed at any time in the General application settings for Role.

Widgets can be added to any page. Click the plus button in the minimized right side menu or the Add New Chart button when it is expanded.

This opens the Add New Widget dialogue.

Use any one or combination of the filter dropdowns to select a subset of metrics and/or enter a query text in any of the free text search input fields to further narrow down the results. All matching metrics will be shown in the list on the left. Select one or more items. Selected metrics are shown in the list on the right. The search can be changed between selection.

Finally, confirm the selection by clicking the Add button of the dialogue.

Newly added widgets are automatically placed in a column so that widgets are evenly distributed on the page. Use the side panel widget settings to change the column, width, height or item position of the widget or use the quick menu for the widget by clicking the pencil symbol in the top right corner of the widget.

To configure a widget select it by clicking on its title or the pencil icon in the top right corner of the widget.

This opens the right settings side panel and shows the detailed configuration of the widget. The side panel can be closed by either deselecting the widget, by clicking on its title again, or by clicking the collapse icon of the right sidebar.

The General widget settings are concerned with the widget’s position within the page and its general appearance.

The Data settings are concerned with what and how the data is shown in the graph of a widget.

The Extras settings are concerned with additional information shown in or around the graph or widget content in general. This includes visual helpers that can be added to a graph of a widget in order to make it easier to for the user to quickly understand the data displayed. In particular these are reference lines and threshold indications.

Besides adding a reference line to the graph the critical and alarming thresholds affect the status evaluation.

Use the colour input to individually override the widget’s colour for waterline, alarming line or critical line in graphs. Press the button right next to it which shows the default colour as configured in the Appearance application settings to reset the individual colour to use the default setting instead. A colour set to the default changes with the default.

The current value of a metric can automatically be categorised as a certain status. For example based on the threshold values of decorations or by encountered errors or missing data. The Status settings allows to set a custom message for a particular status.

The messages support simple markup using *bold* and _italic_.

The values of metric series can be tracked by the server to report values that out of a healthy range. This is represented by states:

State changes to amber or red are reported as alerts. This is shown in the widget they affect. The settings allow filtering these related alerts to prevent them from showing. This makes sense on pages that have dedicated widgets to show alerts or just if users prefer to see the graph instead.

Alerts can occur when a watch is configured for a metric series. A watch describes the conditions and thresholds used to determine a state from the recent values of a metric series. It is either Red (unhealthy), Amber (degraded), Green (healthy) or White (undetermined). A Red or Amber state causes an alert that is shown on top of the graph.

When an alert occurred for a metric shown in a graph the background of the line causing the alert is coloured in Red or Amber default colour until the alert is stopped.

Alerts are considered ongoing as long as the state is Red or Amber. If it is evaluated to Green or White ("unspecified") the alert stops. Stopped or acknowledged alerts are no longer shown on top of line graphs. Other ways to hide an alert from a line graph is to acknowledge the alert by checking its checkbox or to configure the widget’s Alerts Filter setting so that alerts generally aren’t shown for that widget.

To see even stopped or acknowledged alerts add a widget of type Alert Table.

By default, an alert table shows all alerts including stopped and acknowledged alerts. Use the widget Alerts settings to exclude alerts with certain properties.

An alert table shows the overall state of each instance in the table’s legend.

As mentioned before the Alerts settings can equally be used for line graphs to create a more restrictive setting.

Any widget can be removed from any page. Click the pencil symbol in the top right of the widget or its title to open the widget’s settings. On the General widget settings tab you find the Remove button.

Confirm you want to remove the widget

Remember that a page originating from a preset can be reset to recover a widget that was removed accidentally.

The Pages application settings give access to different page management operations as described in detain in section Page Management

Newer versions of Payara InSight allow to configure the colours used in graphs. There is a global colour configuration affecting all graphs.

Themes act as a (p)reset of the data colour palette, default colours and Opacity setting. When switching theme these settings are reset to the theme’s value.

Any further customisation of individual colours can and should be done after applying the theme of choice as switching theme would reset such customisations again. Currently theme settings are individual to the browser and cannot be shared or preconfigured for other users.

Open the watch management as described above and click the Add New Watch button at the top.

The above example shows a relatively simple watch first copied from an existing watch which then is customised. The name of the watch can be anything as long as it is unique. Each watch should have either an Unhealthy and/or a Degraded level. It is also recommended to add a Healthy level. Any value that is no matching any of the levels is White (unspecified).

After giving your watch a unique name select the metric that should be watched. Only single metrics are supported as of yet.

Select the appropriate unit for the selected metric. Depending on the chosen unit thresholds can be given in values of this unit, e.g. when selecting Milliseconds the threshold can be given as 1s for 1 second.

When name, watched metric and unit are set, check any of the states a condition should be formulated for and enter the comparison operator, the threshold and the scope.

The below table describes possible choices for each step of a watch condition.

The below table describes the semantics of the different types of comparison scopes.

After composing the watch conditions press Save to install the watch.

System watches that originate from server modules cannot be changed. But they can be disable and copied to effectively make them editable. Find more in the edit section below.

To edit a user watch open the watch manager, scroll down to the list of User Watches and click the Edit button of the watch that should be edited.

Confirm changes by clicking Update.

When changing the name of the watch a new watch is created with the new name and the old watch continues to exist. It can be deleted afterwards using the Delete button in the User Watches list.

Open the watch manager as Administrator and click the Disable or Enable button of the watch that should be disabled or enabled. The change has immediate effect and can easily be "undone" by toggling the state again. If there were any ongoing alerts due to a watch that gets disabled, these alerts stops. Enabling such a watch again then requires matching the watches start condition again.

The Core page gives an overview of some of the important instance metrics. Each instance in the grid is shown separately.

The Traffic Light Status page (a.k.a. RAG Status for Red-Amber-Green Status) indicates the health status of the server and deployed application using traffic light signals to visualise the current state.

The content of the page is based on Payara Health Checks (needs to be enabled in the server configuration) and MicroProfile Heath checks of deployed applications.

In contrast to most pages this page is not static based on a manually created configuration. Instead the page is populated with widgets based on a query.

For more details on query pages see sections Adding Pages and Page Settings.

The HTTP page gives a rough overview of the state of the HTTP services of each instance.

The JVM pages gives a general overview of the state of the JVM running Payara Server Enterprise.

A page that shows key metrics on the Payara InSight system itself. This is mostly useful to

A page that gives an overview of the state of the server health checks. The individual checks need to be enabled in the server’s HealthCheck configuration.

The Threads page gives detailed information on thread health of the cluster and lists information on stuck or hogging threads. Total number of live and daemon threads are given for reference.

The Request Tracing page overview page shows traces that exceeded the set threshold configures as part of the request tracing server configuration.

The Trace Duration Range widget shows all traces for the same method as a single bar. The length and position of the bar gives the range of total trace duration for all the occurrences that exceeded the threshold. The bar starts at the minimum duration observed and ends at the maximum duration observed in the last minute. The legend shows the average duration and the method traced (innermost trace span operation)

When checking the minimum and/or maximum checkbox in the widgets Extras settings the bar starts and/or ends at these "all time" values instead of the minimum and/or maximum within the last minute.

The Trace Duration Above Threshold widget shows a graph where each point marks the duration of a "slow" request at the moment the requests occurred. Possible alerts are shown on top of the graph.

By clicking on one of the bars in the overview’s Trace Duration Range widget the details of all kept traces for this method can be viewed.

This data corresponds to the traces stored in the trace-store. For each trace, each of the spans corresponds to a bar in this graph.

The details can be sorted by wall-time or by total duration. By default, the traces are sorted longest (slowest) to shortest (fastest) total duration. On the time axis the spans are shown relative to the start of the trace.

The legend gives average durations for each of the spans occurring for the traced method.

When clicking on the bars in the details view the right side panel shows the trace span details of the clicked trace span.

The SQL page gives insight into slow SQL queries for all connection pools configured in Payara Server Enterprise.

The main use of the Alerts page is to check for any server alerts. The page is split into two lists: the upper list containing all ongoing alerts, and the lower list containing past alerts. As always for alert lists both lists are sorted starting with the most recent severe alert progressing to the oldest least severe alert. Annotations associated with alerts are hidden in this view to make room for more alert entries.

Past alerts can be managed by acknowledging the alerts which makes them disappear from the list.

Payara InSight is build with the intention to make visualising user defined metrics really easy. This includes MicroProfile Metrics and MicroProfile Health checks that as defined by deployed application and server itself. It does not require and further configuration to make them available as metrics within Payara InSight.

In addition the metrics selection wizard has additional filters specifically filtering on the properties of MicroProfile Metrics.

When MicroProfile Metrics get translated to InSight series the MP tags become the @ group of the shown series key, the MP metric stays the metric name.

The Application Metrics page is a page that is automatically populated will MicroProfile Metrics based on a query. This means the metrics shown on the page vary depending on what metrics are defined in applications and the server as MicroProfile metrics.

When populating the page the widgets are configured automatically based on the information available in MicroProfile.

For more details on query pages see sections Adding Pages and Page Settings.

The term series is used for the name or key for a particular metric. Each metric has a unique key or series name. Usually these names use tags for form key:value to categorise metrics into groups.

For example:

The series names shown above exemplify conventions used throughout Payara InSight. The first grouping level usually is the ns (short for namespace), the second the @ (short for group). In the example the metrics belong to the jvm namespace and the groupName group within that namespace.

When metrics are selected using the wizard only fully qualified metric series can be selected. This is a limitation of the selection wizard. On the technical level a series can be either a fully qualified series name or a series pattern. Patterns contain wild-cards to match not only one specific metric but a set of metrics. Wild-cards can occur in different places. Examples of this can be found in the query page’s Query Series setting.

For example the Traffic Light Status page uses the query *boldns:health ?:* *. A *bold* wild-card for the metric name means any metric name. The *bold?:* combines a wild-card (tag) value (*bold*) with a wild-card tag name (?). This means any tag name (including none and multiple of them) with any value. So the full *boldns:health ?:* * matches any series that is in ns:health, weather or not is has more tags, while *boldns:health * only would match series in ns:health which do not have further tags.

This feature can be used to automatically show all metrics of a certain pattern in a single widget as it is done by the request tracing page.