Using QRebel

QRebel functions as a standalone web page. The QRebel agents upload data to the secure backend. The data is then analyzed and detailed reports are made available via the QRebel Dashboard.

Tip

We recommend reading the QRebel Quick Start to quickly set up your first project and application.


Dashboard

Dashboard provides the bird’s eye view of the current project. It also provides shortcuts to general QRebel views.

../_images/xrhub_dashboard.png

From top left, the dashboard allows access to the following features:

  • Project select – open the drop-down menu with the current project name to select any other. Bear in mind that additional project names will appear only when you have been invited into other projects.
  • Dashboard – press this button to return to the dashboard home page at any time.
  • Setup – press to gain access to the agent download options.
  • Settings – press to open general QRebel settings.
  • Users – press to open the user management view for the current project.

The body area of the dashboard displays any applications that have been configured for the current project. When no applications have been added, the setup menu is shown instead.


Application

The application view displays performance problem reports for the latest available build or time period. The reports are generated based on a comparison of the application data across the two most recent available builds or versions. When only one build or version is available for analysis, the comparison is performed against a static threshold.

../_images/xrhub_application.png

The following features are available for every application:

  • Application timeline – displays the timeline for all builds and versions recorded for the application. Hovering over timeline entries shows tooltips for the builds and versions.
  • Comparison select tool – this feature can be accessed in the top right corner of the application pane, allowing the user to pick any desired comparison between available data points. By default, QRebel displays a comparison between the two most recent available versions or builds.
  • Issue reports – pressing the report sections will expand them to display more data. Total amount of issues detected for the current comparison are displayed next to the report title.
    • Slow Requests – displays the requests with the greatest performance impact in the current comparison. Hovering over the profile graph for any request will show a more in-depth performance graph. Pressing any slow request entry will display a drill-down trace diff view.
    • Excessive IO – displays entry points with the most excessive input-output issues.
    • Exceptions – displays any exceptions that occurred in the application in the compared builds or versions.

Application settings

Pressing the gear icon next to the application name will display application settings.

../_images/xrhub_application_settings.png

The following threshold settings can be set for every separate application:

  • Relative threshold:
    • Increase (default 1.4) – define the relative multiplier threshold at which an entry point will be reported as an issue by QRebel.
    • Scope (default 10%) – define the relative scope threshold at which an entry point will be reported as an issue by QRebel.
  • Absolute threshold:
    • Latency (default 200 ms) – define the absolute latency threshold at which an entry point will be reported as an issue by QRebel.
    • IO count (default 20) – define the absolute IO count threshold at which an entry point will be reported as an issue by QRebel.

Application data can be deleted from QRebel from the settings view. This feature is available only to administrator level accounts.


Comparison select tool

The comparison select tool is displayed in top right corner of the application view. By default, this tool shows the currently compared builds, versions or time periods. Pressing the comparison select tool will open the following view:

../_images/xrhub_application_comparisontool.png

The following comparison options are available:

  • Builds & Versions – displays all stored data for the current application’s builds and versions. To engage comparison, pick the desired target build or version, then pick another build or version as the baseline of the comparison.
  • Days – displays a calendar-based breakdown of all stored data for the current application. To engage comparison, pick the desired target period, then pick another period as the baseline of the comparison.

Tip

QRebel detects application versions based on your configuration. Builds and version can be customized based on your specific rules. For more information, please refer to managing application versions.


Slow requests

The slow requests section displays the requests with the greatest performance impact. Pressing any slow request entry will display the data in a trace diff view for the comparison.

../_images/xrhub_application_slowrequests.png

This report is split per request as follows:

  • Entry point – the entry point for the request in your application.
  • Profile – a graph displaying the difference between latency profiles. Percentiles that became slower are highlighted in red. Hover over the graph for a more detailed view.
  • Increase – average latency increase.
  • Scope – scope of the regression. Indicates the percent of requests that became slower.
  • 99% (MS) – percentile, showing requests that were faster than this value in the current comparison.
  • Hits – total hits registered in the comparison.
  • Jira – create or review Jira issues linked to the current slow request. For more information, refer to Jira integration.

Excessive IO

The excessive IO section displays the requests with increased IO counts. Pressing any excessive IO entry will display the data in a trace diff view for the comparison. This report is split as follows:

  • Entry point – the entry point for the request in your application.
  • Profile – a graph displaying the difference between the entry point’s IO counts. Percentiles with increased IO counts are highlighted in red. Hover over the graph for a more detailed view.
  • Increase – average increase in IO events.
  • Scope – scope of the regression. Indicates the percentage of requests with increased IO.
  • 99% (IO) – percentile, showing requests with fewer IO events in the current comparison.
  • Hits – total hits registered in the current build or version.
  • Jira – create or review Jira issues linked to the current excessive IO entry. For more information, refer to Jira integration.

Exceptions

The exceptions section displays the exceptions encountered. Pressing any exception entry will display the data in a drill down view. This report is split as follows:

  • Entry point – the entry point for the request in your application.
  • Exception – the exception details.
  • Hits – total hits registered for the exception in the current build or version.
  • Jira – create or review Jira issues linked to the current slow request. For more information, refer to Jira integration.

Agent download

Agent download allows downloading the customized application agent or the generic agent. When downloading the generic agent, the project token and application names need to be provided for the agent to function.

To download and configure the customized application agent, follow the steps listed on the screen.

../_images/xrhub_agentdownload.png

Managing application versions

QRebel supports custom tagging for application builds and versions. The agent only detects builds by default. The build is tagged by a timestamp, based on the first test of that build. You can override the default build tag with a customized tag, for example the last commit hash, Jenkins build number etc. Application versions can be used when you need an additional aggregation layer. For example, when using sprints, a sprint name can be used as the version tag. This allows you to compare performance between sprints or releases.

Use one of the following options to set up custom tags:

Maven

Use your pom.xml to specify custom build and version tags for QRebel.

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
            <!-- or <artifactId>maven-war-plugin</artifactId> -->
        <version>2.1</version>
        ...
        <configuration>
            <warName>petclinic</warName>
            <archive>
                <manifestEntries>
                    <QRebel-App-Version>${project.version}</QRebel-App-Version>
                    <QRebel-App-Build>${maven.build.timestamp}</QRebel-App-Build>
                </manifestEntries>
            </archive>
        ...
      </plugin>
    </plugins>
  </build>
  ...
</project>

For more information: https://maven.apache.org/shared/maven-archiver/examples/manifest.html


Gradle

Include the following in your build.gradle file:

war { // or jar
    version = 'my-version-3.14'
    manifest {
        attributes("QRebel-App-Version": version)
        attributes("QRebel-App-Build": build)
    }
}

For more information: https://docs.gradle.org/current/userguide/java_plugin.html#sec:jar


Ant

Add the following to your jar or war task in build.xml:

<jar>
    <manifest>
        <attribute name="QRebel-App-Version" value="${version}"/>
        <attribute name="QRebel-App-Build" value="${version} ${TODAY}"/>
    </manifest>
</jar>

For more information: https://ant.apache.org/manual/Tasks/manifest.html


JVM arguments

Add the version or build parameter to your application startup. The JVM argument overrides all other version settings.

-javaagent:[/path/to/]qrebel-agent.jar -Dqrebel.app.version=YOUR_APP_VERSION -Dqrebel.app.build=YOUR_APP_BUILD

Enterprise applications (EAR)

Note

Enterprise application compatibility requires QRebel Agent 3.6.219 or newer.

To configure all modules inside an EAR for the same version, the file META-INF/MANIFEST.MF containing the version should be visible to all modules as a class loader resource. When multiple versions are found in the EAR, only one of them is used. Here are some examples on how to configure this for different application servers with Maven. The same overall logic applies to other build systems.

JBoss AS

Create the META-INF/MANIFEST.MF template inside the EAR structure. Once transformed, it is automatically searchable by the application class loader. Note that version.jar in this example is just a folder name – you can use any name as long as it ends with .jar. This forces JBoss to put it on the class path.

Manifest-Version: 1.0
QRebel-App-Version: ${qrebel-version}
QRebel-App-Build: ${qrebel-build}

Define the variables and turn on filtering for the maven-ear-plugin in pom.xml. This way the version variables get replaced.

<project>
   ...
   <properties>
      ...
      <qrebel-version>${project.version}</qrebel-version>
      <qrebel-build>${maven.build.timestamp}</qrebel-build>
      <maven.build.timestamp.format>yyyy-MM-dd HH:mm</maven.build.timestamp.format>
   </properties>
   <build>
      <plugins>
         <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-ear-plugin</artifactId>
            <configuration>
               <filtering>true</filtering>
               ...
            </configuration>
         </plugin>
      </plugins>
   </build>
</project>

Defining the variables in <properties> is intentional since Maven does not support using ${maven.build.timestamp} as a template variable in the resource files.

WebLogic Server

Create the META-INF/MANIFEST.MF template in the APP-INF/classes folder. Once transformed, it is automatically searchable by the application class loader.

Manifest-Version: 1.0
QRebel-App-Version: ${qrebel-version}
QRebel-App-Build: ${qrebel-build}

Define the variables and turn on filtering for maven-ear-plugin in pom.xml. This way the version variables get replaced.

<project>
  ...
  <properties>
    ...
    <qrebel-version>${project.version}</qrebel-version>
    <qrebel-build>${maven.build.timestamp}</qrebel-build>
    <maven.build.timestamp.format>yyyy-MM-dd HH:mm</maven.build.timestamp.format>
  </properties>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-ear-plugin</artifactId>
        <configuration>
          <filtering>true</filtering>
          ...
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

Defining the variables in <properties> is intentional since Maven does not support using ${maven.build.timestamp} as a template variable in the resource files.

WebSphere AS

Place the version into the manifest of an utility JAR module in the EAR. Make sure that this utility is visible to other modules, for example by the Class-Path manifest attribute, referencing the JAR file relative to the EAR.


General settings

QRebel settings provide access to general settings.


Users

User management provides access to a list of all users currently invited into the project. It also allows inviting new members into the project.


Inviting users

To invite users, open Users and locate the Invite members section. Specify the new user’s email and press Invite.