Debug service

Table of Contents
  1. Description

    1. Enabling restricted access in the debug service

  2. Tips and Tricks

    1. Using OPTIONS pages

    2. Passing in HTTP headers through GET parameters

    3. Services with traversable beans

    4. Auto-refreshed pages

    5. Services with queryable beans

1 - Description

The debug service is a general-purpose service that serves as the central location for finding various REST APIs that are useful for debugging.

The debug service is found at /{context-root}/repodebug...

Caveat: It should be noted that this debug service is a REST interface. It does not have a customer-focused user interface. Some form entry pages are provided to make the interface easier to use with a browser. However, a full-blown user interface is purposefully not part of the design.

The debug service is designed to be a self-documenting interface. Using nothing more than a browser, you should be able to figure out how to use the various services. A major component of this design are OPTIONs pages for each service that describe what methods are available for each resource. It's expected that the services be self-explanatory through the use of these OPTIONS page. For this reason, this document will not describe how to use the individual services.

1.1 - Enabling restricted access in the debug service

Some of the debug services here can be dangerous if mishandled or can be considered security holes. For this reason, certain aspects of these services are disabled by default.

These restricted areas can be enabled for specific users in one of two ways:

Note that users given the JazzDebug role do not also need the JazzAdmins role, so the debug role can be assigned to non-JazzAdmins users.

To restrict access to individual sensitive areas, the following system properties can also be used:

The entire debug service can be disabled by setting the system property com.ibm.team.repository.debug.disabled to true.

2 - Tips and Tricks

The following tips and tricks apply to all the pages in general.

2.1 - Using OPTIONS pages

OPTIONS pages are provided for all debug services that describe how to use the service. For example, the OPTIONS page for the System Properties service is shown here:

The page also shows the supported input (Content-Type) and output (Accept) formats supported by the service.

2.2 - Passing in HTTP headers through GET parameters

The Juno framework allows HTTP headers such as Accept and Content-Type to be passed in through GET parameters. This allows the REST interfaces to be easily manipulated and tested using nothing more than a browser. However, the REST interfaces work just as well with a tool like Poster if that's what you are already familiar with.

For example, here's the default HTML view for the System Properties service:

To view the System Properties service in JSON, simply append ?Accept=text/json to the URL. This is functionally equivalent to specifying an "Accept: text/json" header on the HTTP request.

In addition, the &plainText flag forces the response header to always be "text/plain" so that the browser treats it a simple text.

The &Content parameter can be used to pass in HTTP content through POSTs and PUTs. And the &Method parameter can be used to simulate non-GET requests. For example, to create a new system property called a.new.property with a value of foobar, execute this URL:

https://localhost:9443/jazz/repodebug/systemProperties/a.new.property?Method=PUT&Content=foobar

The content parameter itself is a URL-encoded string that can represent arbitrarily-complex POJOs. Refer to documentation on the Juno framework for more information.

2.3 - Services with traversable beans

Some of the debug services add a Traversable converter that allows beans to be traversed using additional URL path information.

The service below is simply serializing the results from calling ManagementFactory.getMemoryManagerMXBeans():

If you want to access a particular child node in this bean, it can be accessed through a URL such as the following:

This is equivalent to running the following in Java code:

String memoryPoolName = ManagementFactory.getMemoryManagerMXBeans().get(0).getMemoryPoolNames().get(1);

In another example, to get the current heap memory information, you can access that field through the following URL:

This is equivalent to running the following in Java code:

MemoryUsage memoryUsage = ManagementFactory.getMemoryMXBean().getHeapMemoryUsage();

Services that support the Traversable converter can be determined by looking at the OPTIONS page.

Note that on some services, the Traversable converter may be defined on individual methods instead of the entire class.

2.4 - Auto-refreshed pages

The Juno API allows you to specify the HTTP header "x-response-headers" which essentially just tells the framework to pass through the specified headers into the response.

This feature can be useful if you want to watch a particular page but don't want to keep hitting the refresh button on the page. To do so, simply pass in this header as a GET parameter to return a "Refresh: 1" header on the response:

https://localhost:9443/jazz/repodebug/mxBeans/memory/heapMemoryUsage?x-response-headers={Refresh=1}

This triggers your browser to refresh the page every second.

2.5 - Services with queryable beans

Some of the debug services add a Queryable converter that allows collections of beans to be filtered by providing query, sort, and view parameters.

For example, the JVM threads service uses the Queryable converter to provide filtering capability on currently running JVM threads. In this example, we return only threads matching the name Asynchronous* that are in the WAITING state with a priority greater than 4. We sort the results by id, and return only the name, priority, and state columns.

It should be noted that the Queryable converter tends to not be very efficient since it must copy the entire POJO model into a generic tabular structure before being manipulated.

Refer to documentation on the Juno framework for more information.