Advanced features¶

Here you can find details on how to access some of the more advanced XRebel functionality.

XRebel Standalone UI¶

XRebel toolbar injection does not apply to Web Services, because these applications do not have any actual web page contents (into which we would usually inject the toolbar). The same applies to applications that do not allow injecting the toolbar. There is a workaround for this.

Open a new browser window.
Enter your application URL and add /xrebel at the end of it.
The XRebel standalone UI is displayed.

You can now use the XRebel functionality, with data polled from your Web Services applications. Enjoy!

Custom profiling¶

XRebel Agents can be configured to use a customized profiling setup. This is particularly useful for adding custom names for transactions otherwise treated as “unidentified”. To do this:

Download the customized configuration file.
Edit the file to set up customized entry points. Detailed instructions are contained within.
Save the file in ~/.xrebel.
Restart your application.

Asynchronous Tracing¶

XRebel allows out-of-the-box tracing of some asynchronous tasks running in the background. When e.g. HTTP requests spin out background tasks it’s extremely valuable to gain insight into what happens behind the scenes.

Asynchronous tasks are clearly marked within the trace tree.

asyncicon1 is used for the async fork, asyncicon2 to show the join point and asyncicon3 for the location if async fork and join are in the same branch

Here’s how the visual representation will look like when an async task has been detected and traced:

As seen above, async tasks have a dedicated menu in the main request header. Expanding the menu will give you a list of tasks.

Since by nature async tasks are run in the background, some are lengthy operations. In order to not delay the sending of traces from the XRebel agent to the dashboard too much, we’ve set up a cap time of 10 seconds after which XRebel will stop tracing the async task and send the data without the trace.

The menu gives you a quick overview with links to all async tasks, and it quickly tells you if the cap time was reached.

Fork and join points¶

Typically, asynchronous tasks are forked at one code location and later joined by another. In order to capture that scenario, the execution trace will include a visual representation of both the asyncicon1 fork point and the asyncicon2 join point. This looks like this:

A fork point will be marked with a link icon within the trace and a link button Go to join to allow navigation to the join location in the trace.

Ongoing asynchronous operations¶

XRebel provides live tracing data for requests, which has some implications regarding potential async background tasks. In order to have immediate data available, the data will be presented in the toolbar as soon as the main request returns. What about async tasks that are still ongoing at that point in time?

Ongoing async operations have a special representation in the UI of the trace as shown below:

The ongoing spinner icon will be shown for the duration of the cap time, unless it finishes before that time. If the cap time is not sufficient to complete the async task, the tracing will be stopped and the full trace will not be shown.

You can control the cap time by using the JVM property -Dxrebel.async.wait_timeout.sec=40.

XRebel with single page applications and AJAX¶

XRebel can be used with applications where frontend and backend are served by separate instances. These applications require more configuration for injecting the toolbar.

To inject the toolbar into a single page application, add the following code snippet to the HTML source before closing the <body> tag:

<script>
window.XREBEL_SERVERS = ["http://backend1.mycompany:1337/MyApplication"];

  (function() {
    var script = document.createElement("script");
    script.src = window.XREBEL_SERVERS[0] + "/a65f4bf22bdd793dca6963ffe7fa0c62/resources/init.min.js";
    document.body.appendChild(script);
  }());
</script>

Note

window.XREBEL_SERVERS is a plain JavaScript array. You can specify multiple Java backends by separating the URLs with a comma:

window.XREBEL_SERVERS = ["URL1", "URL2"]

Warning

Do not forget to remove the toolbar injection code when moving to a production environment!

XRebel ignore lists¶

XRebel allows excluding specified classes from tracing instrumentation (application performance). Known fast classes are excluded by default and can be re-included where necessary. You can manually ignore classes by listing them as regular expressions in ~/.xrebel/traces-blacklist.txt. Additional known fast middleware classes are listed in ~/.xrebel/expanded-traces-blacklist.txt. This secondary blacklist can be disabled by using the XRebel launch parameter -Dxrebel.traces.expanded_blacklist=false (default value: true).

Known slow middleware classes are listed in the separate ~/.xrebel/traces-blacklist-exclusions.txt file. This exclusion list can also be disabled by the launch parameter -Dxrebel.traces.expanded_blacklist=false (default value: true).

XRebel also excludes static and transient fields when calculating the size of an object. You can also manually ignore classes and packages by listing them in the file ~/.xrebel/session-blacklist.txt.

XRebel launch parameters¶

The following advanced XRebel launch parameters can be used for further configuration:

-Dxrebel.license.file=/path/to/xrebel.lic (default value: {rebel.base}/.xrebel) – Specify the XRebel license file location
-Dxrebel.license.url=Rebel Licenses Team URL (default value: false) – Specify the URL where licensing is hosted.
-Dxrebel.license.email=User Email Address (default value: false) – Specify email of user to activate product.
-Dxrebel.single_app_mode=true|false (default value: true) – Consider all deployments to be part of a single application. This reports activity from different deployment units to one and the same toolbar.
-Dxrebel.injection.log_response=true|false (default: false) – When true, the content of HTTP servlet responses will be logged to xrebel.log. This is meant to help debug cases when the toolbar is not properly injected into the application’s HTML.
-Dxrebel.session.include_transient_fields=true|false (default value: false) – When true, fields with the transient modifier will be considered when constructing the session graph. By default, all transient fields are ignored and objects reachable only through transient fields are not considered to be part of the session.
-Dxrebel.session.global_snapshot_id=true|false (default value: false) – When false, session snapshots are kept track of per session. When true, all session snapshots are kept track of as one set. Setting this to true may be helpful when debugging scenarios where the underlying session changes, such as login/logout.
-Dxrebel.session.snapshots_per_session=n (default value: 1) – The maximum number of session snapshots to keep per scope (session, or global, depending on xrebel.session.global_snapshot_id). Increasing this limit may increase memory use, but will allow exploring the session snapshot even after the next snapshot is taken. This may be helpful when using multiple tabs simultaneously.
-Dxrebel.browser.console_log=true|false (default value: false) – When true, the client side XRebel log will be written into the browser console.
-Dxrebel.injection=true|false (default value: true) – Disables the toolbar injection into application HTML. Add /xrebel to your application URL to view the toolbar in a separate tab (this opens the alternative UI view).
-Dxrebel.traces.filter_resources=true|false (default value: true) – Prevents displaying resource requests in the Application performance view.
-Dxrebel.include_all_io=true|false (default value: true) – Enables the display of all detected IO events. IO events that cannot be categorized are displayed as Unidentified.
-Dxrebel.sql.format=true|false (default value: true) – Enables formatting of SQL queries.
-Dxrebel.traces.expanded_blacklist=true|false (default value: true) – Enables using the expanded blacklist for excluded classes.
-Dxrebel.traces.all=true|false (default value: false) – Enables tracing for all contexts.
- -Dxrebel.traces.jms=true|false (default value: false) – Enables tracing for JMS.
- -Dxrebel.traces.scheduler=true|false (default value: false) – Enables tracing for ScheduledExecutorService.
- -Dxrebel.traces.quartz=true|false (default value: false) – Enables tracing for Quartz.
- -Dxrebel.traces.rabbitmq=true|false (default value: false) – Enables tracing for RabbitMQ.

Individual module integration parameters¶

All individual integrations for modules can be disabled at will. The following advanced XRebel launch parameters can be used:

-Dxrebel.module.http.HttpURLConnection=true|false (default value: true) – Disables collecting IQ queries from java.net.HttpURLConnection usage.
-Dxrebel.module.http.HttpCore=true|false (default value: true) – Disables collecting IO queries from Apache HttpCore 4.x usage.
-Dxrebel.module.http.HttpClient3=true|false (default value: true) – Disables collecting IO queries from Apache HttpClient 3.x usage.
-Dxrebel.module.mongodb=true|false (default value: true) – Disables collecting IO queries from MongoDB driver usage.
-Dxrebel.module.hbase=true|false (default value: true) – Disables collecting IO queries from HBase driver usage.
-Dxrebel.module.redis=true|false (default value: true) – Disables collecting IO queries from Redis driver usage.
-Dxrebel.module.cassandra=true|false (default value: true) – Disables collecting IO queries from Cassandra driver usage.
-Dxrebel.module.orm=true|false (default value: true) – Disables collecting information about ORM queries, including Hibernate JPA queries.
-Dxrebel.module.equinox=true|false (default value: true) – Disables support for Equinox class loaders (boot delegation).
-Dxrebel.module.rmi=true|false (default value: true) – Disables collecting IO queries from RMI (java.rmi) remote object invocations.
-Dxrebel.module.traces=true|false (default value: true) – Enables the application performance view.
-Dxrebel.module.session=true|false (default value: true) – Disables taking session snapshots.
-Dxrebel.module.springloaded=true|false (default value: true) – Disables Spring Loaded agent when detected.
-Dxrebel.module.async=true|false (default value: true) – Disables collecting IO queries from asynchronously executed threads.
-Dxrebel.module.quartz=true|false (default value: true) – Disables collecting IO queries within a Quartz job context.
-Dxrebel.module.jms=true|false (default value: true) – Disables collecting IO queries within JMS MessageListener.onMessage() context.
-Dxrebel.module.scheduler=true|false (default value: true) – Disables collecting IO queries for ScheduledThreadPoolExecutor tasks.
-Dxrebel.module.rabbitmq=true|false (default value: true) – Disables collecting IO events within RabbitMQ consumer.handleDelivery() context and outgoing messages.
-Dxrebel.module.remote_events=true|false (default value: true) – Disables collecting and displaying data from remote XRebel-enabled web services (microservices).
-Dxrebel.module.jdbc=true|false (default value: true) – Disable collecting IO queries from JDBC usage.
- -Dxrebel.module.jdbc.sql=true|false (default value: true) – Disables collecting IO queries from relational database JDBC usage. Requires -Dxrebel.module.jdbc to be true.
- -Dxrebel.module.jdbc.neo4j=true|false (default value: true) – Disables collecting IO queries from Neo4j JDBC usage. Requires -Dxrebel.module.jdbc to be true.
- -Dxrebel.module.jdbc.cassandra=true|false (default value: true) – Disables collecting IO queries from Cassandra JDBC usage. Requires -Dxrebel.module.jdbc to be true.
- -Dxrebel.module.jdbc.phoenix=true|false (default value: true) – Disables collecting IO queries from Apache Phoenix (HBase) usage. Requires -Dxrebel.module.jdbc to be true.

Debugging with XRebel enabled¶

When XRebel is enabled, it could prove difficult to step into XRebel methods. To resolve this issue, configure your IDEs to enable step filtering for com.zeroturnaound.xrebel.*.

Step filtering with Eclipse¶

Open Preferences > Java > Debug > Step Filtering.
Enable Use Step Filters.
Add a filter for com.zeroturnaround.xrebel.* and java.*.

Step filtering with IntelliJ IDEA¶

Open Settings > Build, Execution, Deployment > Debugger > Stepping.
Enable Do not step into the classes.
Add a filter for com.zeroturnaround.xrebel.*.

Microservices¶

XRebel can analyze distributed applications or microservices. To do this, an XRebel agent needs to run with every separate application in the microservices structure. All agents have to be activated using a valid license. The XRebel Agents communicate using HTTP. The collected data is collected and displayed in the view within the front-end (web) application.

Transactions marked with the icon originate from microservice applications running with XRebel enabled.

For more information about using XRebel, please refer to the using XRebel chapter.

Automatic updates¶

Allows XRebel to download the latest version in the background and then automatically apply them on server restart enabling you to always utilize the latest features in XRebel. This feature is turned on by default.

In-Application configuration¶

In order to disable automatic updates, go to Settings->Settings and toggle off “Enable automatic updates”

Command line configuration¶

The following XRebel launch parameter can be used to disable automatic updates: -Dxrebel.autoUpdate=true|false (default value: true).

Advanced features¶

XRebel Standalone UI¶

Custom profiling¶