Advanced features

This chapter details advanced configuration options for XRebel Hub. Please head over to https://zeroturnaround.com/software/xrebel-hub/ for more information about XRebel Hub.


Microservices configuration

In order to profile distributed applications or microservices, add XRebel Hub Agents to all connected applications.

../_images/xrhub-microservices.png

Keep in mind that there are two methods to collect microservices transactions:

  1. Configuring all applications to share the same name. All traces will be collected into one application view on the dashboard using that name.
  2. Using separate names for all connected applications. Transactions are separately collected and displayed under each separate application. The top level applications will still display all transactions from connected applications.

Note

End-to-end transactions will be highlighted using the remote2icon icon.


Managing application versions

XRebel Hub 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 XRebel Hub.

<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>
                    <XRebel-Hub-App-Version>${project.version}</XRebel-Hub-App-Version>
                    <XRebel-Hub-App-Build>${maven.build.timestamp}</XRebel-Hub-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("XRebel-Hub-App-Version": version)
        attributes("XRebel-Hub-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="XRebel-Hub-App-Version" value="${version}"/>
        <attribute name="XRebel-Hub-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/]xrebel-hub-agent.jar -Dxrebel.hub.app.version=YOUR_APP_VERSION -Dxrebel.hub.app.build=YOUR_APP_BUILD

Enterprise applications (EAR)

Note

Enterprise application compatibility requires XRebel Hub 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
XRebel-Hub-App-Version: ${xhub-version}
XRebel-Hub-App-Build: ${xhub-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>
      ...
      <xhub-version>${project.version}</xhub-version>
      <xhub-build>${maven.build.timestamp}</xhub-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
XRebel-Hub-App-Version: ${xhub-version}
XRebel-Hub-App-Build: ${xhub-build}

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

<project>
  ...
  <properties>
    ...
    <xhub-version>${project.version}</xhub-version>
    <xhub-build>${maven.build.timestamp}</xhub-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.


Custom profiling

XRebel Hub Agents can be configured to use a customized profiling setup. This is useful for adding requests that would normally not be picked up by XRebel Hub (e.g. desktop applications, non-HTTP requests). To do this:

  1. Download the customized configuration file.
  2. Edit the file to set up customized entry points. Detailed instructions are contained within.
  3. Save the file in the same location as the XRebel Hub Agent JAR file.
  4. Restart your application.

Multiple applications running in a single container

Multiple applications running in a single container can be detected using the following VM argument: -Dxrebel.hub.app_auto_discovery=true (defaults to false).

The application name is read form the <display-name> element of your web.xml. When not provided, the application’s context root is displayed as the application name in XRebel Hub.