Debug service
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.
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:
JazzDebug
authentication role.tomcat-users.xml
file and adding a new JazzDebug
role.
com.ibm.team.repository.debug.restricted.authorizedUsers
which can either
be a comma-delimited list of users, or JazzAdmins
users.
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:
com.ibm.team.repository.debug.restricted.systemProperties.authorizedUsers
- Allow system properties to be updated.
com.ibm.team.repository.debug.restricted.jvmDump.authorizedUsers
- Allow dump files to be generated.
com.ibm.team.repository.debug.restricted.mxBeans.authorizedUsers
- Allow management bean setters to be called.
com.ibm.team.repository.debug.restricted.logConfig.authorizedUsers
- Allow log levels to be altered.
The entire debug service can be disabled by setting the system property com.ibm.team.repository.debug.disabled
to
The following tips and tricks apply to all the pages in general.
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.
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
In addition, the &plainText
flag forces the response header to always be
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.
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.
:
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.
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.
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.
The Juno API allows you to specify the HTTP header
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
https://localhost:9443/jazz/repodebug/mxBeans/memory/heapMemoryUsage?x-response-headers={Refresh=1}
This triggers your browser to refresh the page every second.
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.