Installation

Download and setup

  1. Log in and follow the instructions on the dashboard to get started with a new project.
  2. Download the QRebel agent from http://hub.qrebel.com/ for your project.
  3. Setup Builds and Versions for your app, so that you can easily track your builds in the QRebel dashboard. See Configure build names.
  4. Add the following parameter to JVM arguments for the application server. Make sure the path that you refer to contains the qrebel-agent.jar file:
-javaagent:[path/to/]qrebel-agent.jar

Using multiple agents in the same JVM process? You need to specify the -javaagent parameter for every agent:

-javaagent:[path/to/]qrebel-agent.jar -javaagent:[path/to/]jrebel-agent.jar
  1. And you are done! Launch your server and application. The agent will start sending profiling data to the QRebel servers as soon as it is successfully launched.

The first build and initial collected data

The first time the agent is launched it collects data and sends it to the QRebel dashboard. You’ll then be able to inspect the data (give it a few moments to show up). This data will establish the initial baseline for detecting performance regressions in your app.

We recommend that you browse through the captured data to validate that your endpoints are all being tracked by the QRebel agent. In case you have a microservice architecture make sure to read the documentation. In case endpoints which you expect to show up aren’t please make sure that you run tests in which the endpoint in question is hit. In case it still doesn’t show up, QRebel might need a little assistance with custom profiling.

Once you’re happy with the data you see for the initial build you’re set up for automatic detection of regressions starting from the next build.

Note

We strongly recommend setting up Builds and Versions to ease the use of the QRebel dashboard.

Adding QRebel to your server

Having trouble getting QRebel to work with your application server? This chapter details the correct examples for how to add the JVM parameter to your server startup, using either an IDE or running your server without it. You need to define the QRebel agent within your server’s startup script. This chapter provides QRebel agent running examples for servers that are supported.


GlassFish

  1. Access your GlassFish Administration Console.
  2. Open Configuration > JVM Settings > JVM Options.
  3. Press Add JVM Option and insert the following:
-javaagent:[path/to/]qrebel-agent.jar
  1. Press Save and don’t forget to restart your server.

JBoss

JBoss on Windows

  1. Access your JBoss home folder.
  2. Open the bin folder.
  3. Add the following line at the end of standalone.conf.bat:
JAVA_OPTS="-javaagent:[path/to/]qrebel-agent.jar" %JAVA_OPTS
  1. Save the file and start JBoss.

JBoss on Mac OS and Linux

  1. Access your JBoss home folder.
  2. Open the bin folder.
  3. Add the following line at the end of standalone.conf:
JAVA_OPTS="-javaagent:[path/to/]qrebel-agent.jar $JAVA_OPTS"
  1. Save the file and start JBoss.

JBoss Domain

  1. Access your JBoss Domain configuration folder JBOSS_HOME/domain/configuration.

  2. Open configuration.xml.

  3. Locate your desired server group.

  4. Add the following option to the configuration:

    <jvm-options>
      <option value="-javaagent:[path/to/]qrebel-agent.jar"/>
    </jvm-options>
    
  5. Save configuration.xml and restart the server.


Jetty

Jetty on Windows

  1. Add the following to the command line:
-javaagent:[path/to/]qrebel-agent.jar
  1. Run Jetty.

Jetty on Mac OS and Linux

  1. Access your Jetty home folder.
  2. Open the bin folder.
  3. Add the following line in jetty.sh after the line # JAVA_OPTIONS:
JAVA_OPTIONS="-javaagent:[path/to/]qrebel-agent.jar $JAVA_OPTIONS"
  1. Save the file and start Jetty.

Resin

  1. Access your Resin home folder.
  2. Open the conf folder.
  3. Edit the resin.properties file. Locate jvm_args.
  4. Add the QRebel parameter:
jvm_args=-javaagent:[path/to]qrebel-agent.jar
  1. Save the file and start Resin.

Note

Alternatively, you can include the QRebel parameter in the resin.xml file. To do this, add the following within the <server> tags: <jvm-arg>-javaagent:[path/to]qrebel-agent.jar</jvm-arg>

Warning

You only need to configure the JVM parameter once. Pick either the properties file or the xml file. Do not add the JVM parameter in both places.


Tomcat

Tomcat on Windows

  1. Access your Tomcat home folder.
  2. Open the bin folder.
  3. Add the following line to catalina.bat:
CATALINA_OPTS="-javaagent:[path/to/]qrebel-agent.jar" %CATALINA_OPTS
  1. Save the file and start Tomcat.

Tomcat on Mac OS and Linux

  1. Access your Tomcat home folder.
  2. Open the bin folder.
  3. Add the following line to catalina.sh:
CATALINA_OPTS="-javaagent:[path/to/]qrebel-agent.jar $CATALINA_OPTS"
  1. Save the file and start Tomcat.

WebLogic

WebLogic on Windows

  1. Access your WebLogic home folder.
  2. Open the bin folder.
  3. Add the following line to startWebLogic.cmd after the setDomainEnv.sh call:
JAVA_OPTIONS="-javaagent:[path/to/]qrebel-agent.jar" %{JAVA_OPTIONS}
  1. Save the file and start WebLogic.

WebLogic on Mac OS and Linux

  1. Access your WebLogic home folder.
  2. Open the bin folder.
  3. Add the following line to startWebLogic.sh after the setDomainEnv.sh call:
JAVA_OPTIONS="-javaagent:[path/to/]qrebel-agent.jar ${JAVA_OPTIONS}"
  1. Save the file and start WebLogic.

WebSphere

Windows

  1. Start the IBM WebSphere server and open the administrative console.
  2. In the Admin Console open Servers > Application servers. Select the server your application is deployed to.
  3. Select Java and Process Management > Process Definition.
  4. Select Java Virtual Machine.
  5. Insert the following line into Generic JVM arguments for WebSphere:
-noverify -Xshareclasses:none -javaagent:[c:\path\to\]qrebel-agent.jar
  1. Press OK. When asked, save the master configuration and restart the server.

Linux and Mac OS

  1. Start the IBM WebSphere server and open the administrative console.
  2. In the Administration Console open Servers > Application Servers. Select the server your application is deployed to.
  3. Select Java and Process Management > Process Definition.
  4. Select Java Virtual Machine.
  5. Insert the following line into Generic JVM arguments for WebSphere:
-noverify -Xshareclasses:none -javaagent:[/path/to/]qrebel-agent.jar
  1. Press OK. When asked, save the master configuration and restart the server.

WebSphere Application Server Liberty Profile

To run QRebel, you need to specify the QRebel JVM argument in the JVM_ARGS environment variable before you launch the startup script:

  1. Run the JVM arguments setting command using the server command line:
  2. When using Mac OS or Linux:
export JVM_ARGS="-javaagent:[path/to]qrebel-agent.jar"
  1. When using Windows:
set JVM_ARGS=-javaagent:[path/to]qrebel-agent.jar
  1. Launch the server.

When you start your application server with this argument configured, the QRebel agent is loaded at startup.


WildFly

WildFly on Windows

  1. Access your WildFly home folder.
  2. Open the bin folder.
  3. Add the following line at the end of standalone.conf.bat:
JAVA_OPTS="-javaagent:[path/to/]qrebel-agent.jar" %JAVA_OPTS
  1. Save the file and start WildFly.

WildFly on Mac OS and Linux

  1. Access your WildFly home folder.
  2. Open the bin folder.
  3. Add the following line at the end of standalone.conf:
JAVA_OPTS="-javaagent:[path/to/]qrebel-agent.jar $JAVA_OPTS"
  1. Save the file and start WildFly.

Standalone JAR application

To add the QRebel agent to a standalone JAR file, insert the -javaagent option before the JAR file declaration:

java -javaagent:[path/to/]qrebel-agent.jar -jar your-standalone.jar

Configure build names

For proper usage QRebel requires custom tagging of build names and optionally versions. Depending on your project versioning scheme examples of build names include the last commit hash, Jenkins build number, a build timestamp etc. Additionally versions can be used when you need an additional aggregation layer which will help you navigate the builds in QRebel. Typically, projects have a well-defined version, but other times when using sprints, a sprint name can be used as the version tag. This allows you to easily compare performance between sprints and/or releases.

Note

Failure to complete this setup may in some cases lead to a disfunctioning product. In case the build name is not specified following the below instructions, QRebel attempts to automatically fingerprint binaries to differentiate builds from each other when changes are made. However, in some cases QRebel is unable to do so, and you will be met with a warning message on the QRebel dashboard urging you to complete the build name setup.

Select your build system from the left hand side menu to find specific configuration options.

Maven

For maven please use your pom.xml to specify custom build and version tags for QRebel.

maven-jar-plugin

If you package your app or module with the maven-jar-plugin use the following configuration:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.1.1</version>
        ...
        <configuration>
            <archive>
                <manifestEntries>
                    <QRebel-App-Build>${maven.build.timestamp}</QRebel-App-Build>
                    <QRebel-App-Version>${project.version}</QRebel-App-Version>
                </manifestEntries>
            </archive>
        ...
      </plugin>
    </plugins>
  </build>
  ...
</project>

maven-war-plugin

If you package your app or module with the maven-war-plugin use the following configuration:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-war-plugin</artifactId>
        <version>3.2.2</version>
          ...
        <configuration>
            <archive>
              ...
                <manifestEntries>
                    <QRebel-App-Build>${maven.build.timestamp}</QRebel-App-Build>
                    <QRebel-App-Version>${project.version}</QRebel-App-Version>
                </manifestEntries>
              ...
            </archive>
        ...
      </plugin>
    </plugins>
  </build>
  ...
</project>

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

Maven and local development with IntelliJ

No manifest generated in exploded development with Intellij? That’s a known bug! Please use the following workaround to generate a simple placeholder manifest for local testing purposes. Also, remember to verify that the real manifest is being generated with the QRebel attributes inside the jar/war file before uploading to your automated testing environment.

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <version>3.3.0</version>
  <executions>
    <execution>
      <id>bundle-manifest</id>
      <phase>process-classes</phase>
      <goals>
        <goal>manifest</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <archive>
      <index>true</index>
      <manifest>
        <addDefaultSpecificationEntries>false</addDefaultSpecificationEntries>
        <addDefaultImplementationEntries>false</addDefaultImplementationEntries>
      </manifest>
      <manifestEntries>
        <QRebel-App-Build>${maven.build.timestamp}</QRebel-App-Build>
        <QRebel-App-Version>${project.version}</QRebel-App-Version>
      </manifestEntries>
    </archive>
  </configuration>
</plugin>

Gradle

Include the following in your build.gradle file:

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

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

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


JVM arguments

Add the build (and optionally version) parameter to your application startup. The JVM argument overrides all other specified build and version values.

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

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-Build: ${qrebel-build}
QRebel-App-Version: ${qrebel-version}

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-build>${maven.build.timestamp}</qrebel-build>
      <maven.build.timestamp.format>yyyy-MM-dd HH:mm</maven.build.timestamp.format>
      <qrebel-version>${project.version}</qrebel-version>
   </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-Build: ${qrebel-build}
QRebel-App-Version: ${qrebel-version}

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

<project>
  ...
  <properties>
    ...
    <qrebel-build>${maven.build.timestamp}</qrebel-build>
    <maven.build.timestamp.format>yyyy-MM-dd HH:mm</maven.build.timestamp.format>
    <qrebel-version>${project.version}</qrebel-version>
  </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.


Build and version names FAQ and troubleshooting

  • I don’t want to create a new build on the QRebel dashboard for each and every commit all devs make!

The default behavior of QRebel is that each build corresponds to a unique binary. Hence, if you configured the build names according to the above configuration, you’ll see one build for each commit, because any new commit will cause a new timestamp to be used.

In case you want to aggregate all data from all builds on a daily basis instead, this is very easy. E.g. for maven one alternative would be to add <maven.build.timestamp.format>yyyy-MM-dd</maven.build.timestamp.format> inside the properties section. This will cause all builds (with the same project version) to become aggregated into one synthetic build in the QRebel dashboard. Please keep in mind, that all issues detected from that build can of course be caused by each and every single commit during that perticular day.

  • Do I have to specify both a version name and a build name?

No, only build names are required to ensure proper product usage. Version names are optional and they provide the flexibillity to aggregate builds under a version tag.

  • How can I use my jenkins build job number as the build name in QRebel?

Quite simple. For example for maven use this line inside the manifest entries section for the :

<manifestEntries>
    <QRebel-App-Build>${env.BUILD_NUMBER}<QRebel-App-Build>
</manifestEntries>

Jenkins should by default populate the env.BUILD_NUMBER environment variable and you’re all set.

  • How can I differentiate nodes/slaves in my CI build server on the QRebel dashboard?

There are a number of ways this can be achieved depending on how you want to aggregate the data on the QRebel dashboard:

  1. You can create a separate app from the QRebel dashboard for each node you want to specifically monitor.
  2. You can aggregate into the same app, but have the Jenkins job pass on a specific build name that includes the node to the JVM arguments, i.e. -Dqrebel.app.build=YOUR_APP_BUILD. Note that this will override the QRebel build naming attributes within your manifest.

QRebel with Docker

To run QRebel with your Docker container, include the agent file in the Docker image and make sure it gets started with your application. The following is a generic example of running the QRebel with Docker using a default Tomcat image.

  1. Create the Dockerfile with the following content (replacing [projecttoken] with the desired project token from QRebel):
FROM tomcat:8.0
RUN wget -O /qrebel-agent.jar https://hub.qrebel.com/getagent/qrebel-agent.jar
ENV JAVA_OPTS="-javaagent:/qrebel-agent.jar -Dqrebel.auth_token=[projecttoken] -Dqrebel.app.id=[app-ID]"

Note

Find the app ID under the configuration section of the generic agent download menu icon.

Legacy configuration (using app name and not app ID)

FROM tomcat:8.0
RUN wget -O /qrebel-agent.jar https://hub.qrebel.com/getagent/qrebel-agent.jar
ENV JAVA_OPTS="-javaagent:/qrebel-agent.jar -Dqrebel.auth_token=[projecttoken] -Dqrebel.app.name=[optional-app-name]"
  1. Save the Dockerfile.
  2. Build your Docker image using $ docker build -t [desired image title] .

And you are done! Run your Docker container when ready. Do not forget to deploy your application.