Principles

NetKernel requests originate as a root request issued by a transport. A root request will typically cause many sub-requests to be issued each of which returns information required to build the final returned resource representation. The Request Visualizer Tool allows you to fully explore the complete set of sub-requests for each captured root request in an easy to use visual display tool.

Request Visualization

The Request Visualizer will capture information about all root requests that match a regular expression pattern. Once captured, the tool allows you to explore each root request and all of its sub-requests.

To capture root requests first enter a regular expression pattern to match those requests that are of interest. Then begin the capture process by pressing the "start" button in the Request Visualizer Tool. (This causes the "start" button to change into a "stop" button). Once started, NetKernel captures information about all requests that match the regular expression in the match field. The "clear" button can be used at any time to release captured root requests from memory. The "refresh" button is used to update the browser window with the latest root request information.

Capturing root requests is a time and memory intensive operation. To speed up the process and to insure that you don't exhaust the Java heap space, increase the initial heap in your configuration by using the -Xms and -Xmx Java runtime initialization parameters. A combination that may work well is:

java ...  -Xms128M -Xm192M

Setting Java runtime parameters is described in the NetKernel Installation Documentation. Additionally, use the Request Visualizer tool only while you are actively investigating one or a few requests. If you are concerned about memory use, use the Memory Monitor. It should be noted that NetKernel is frugal with memory and applications running without request capturing activated are very memory efficient.

Request Visualizer Tool Display

After the Request Visualizer has been able to capture the root requests of interest, press the "refresh" button and the tool will display a list of root requests it has captured.

The following illustrates a sample trace report showing a request for this page you are reading. (If you want to duplicate this remember to issue a hot restart to clear the cache, start request tracing and then re-request this page) The first line in the table displays the root request for the documentation page and the second (and subsequent requests, which are not shown) is for supporting resources such as CSS files, images, etc.

In the Request Visualizer Tool display, each root request line entry is an active link. Click on the root request entry to show the Traced Detail display page (described below).

Root Request	Timestamp	Duration
http://localhost:1060/book/solutiondeveloperguide/doc_ura_requestvisualizer	14:43:49.851	4997
http://localhost:1060/xslib/styles/xmlverbatim.css	14:43:54.849	3

Trace Detail Display

While the Request Visualizer Tool display page lists all of the root requests, the Trace Detail display page expands a single root request and shows all of the sub-request issued to create the final resource representation. In NetKernel, applications are created by composing resources from smaller resources. The Trace Detail display page will show you all of the components dynamically used to fullfill each root request. It will also illustrate that already composed partial results can be retrieved from cache instead of being recomputed. If the request requires the assembly of many resources, this display can be very deep. Or if the results are already in cache, the display will be shallow.

The Accessor Callstack column contains a hierarchical view of all software endpoints used to fulfill the root request. On each line that contains an endpoint that issues one or more sub-requests a hierarchical display control is provided. Press the "-" icon to contract the display and the "+" icon to expand the display.

Column	Display
Accessor Callstack	The accessor callstack displays the complete set of all sub-requests needed to create the final resource representation. Each item in the accessor callstack is a link. Clicking on one will bring up the Traced Request Detail Page showing the final level of trace detail.
Module	The NetKernel module hosting the current endpoint.
Verb	The request verb which can be either SOURCE, SINK, NEW, EXSITS, DELETE or META.
Request URI	The Request URI is the URI for the sub-request documented on the display line. The first line contains the root request and the initial URI. All subsequent lines contain the sub-request URIs.
Cost	Each accessor can attach an estimated cost to each response. For each line the displayed cost is the sum of all sub-request costs plus the cost added by the current endpoint accessor.
$$	A coloured "traffic light" indication of cacheability: Green indicates a cacheable resource. Amber indicates a resource that "could" be cached but isn't. (See expiry in the request detail page for a reason) Red indicates a resource that cannot be cached.
Response Aspects	Each returned resource representation in NetKernel 3 can have one or more associated Aspects. All aspect associated with the current representation are listed. Clicking on the list will cause the trace tool to attempt to display their value. Some aspects may lack a transreptor to provide an appropriate display.

Traced Request Detail Page

The Traced Request Detail Page contains the final level of trace information about a specific request. It can be reached by clicking on any entry in the Accessor Callstack column of the Trace Detail page. The Traced Request Detail page is divided into the sections: Request, Resolution, Endpoint and Response.

Request

The request section contains details about the current request of interest. The fields are described below.

Verb is the request verb which can be either SOURCE, SINK, NEW, EXISTS, DELETE or META.

URI is the resource identifier.

Super Stack displays the stacked set of contexts for the current request. The top most context is the fulcrum in which a transport initiated the request. Each subsequent line in the super stack is a context into which this request or a sub-request has been injected.

Arguments contains a table with all arguments associated with this request. Each argument occupies on row of the table and includes the Name, URI and Value (where available). This field is empty if the request has no arguments.

Representation is the aspect (represented by a Java class) requested for the returned resource representation. This field is empty if no specific aspect class was requested.

Resolution

Resolution is the process of finding an endpoint accessor that has a mapping for the request URI. In this section the resolution trace is displayed from the starting context until a match is found.

The first line of the resolution trace show the URI that is being resolved. The second line displays the starting module, the context in which the resolution begins. Subsequent lines indicate the mappings that are tested for a match. If a match is made on an imported module, then the resolution enters into that module's context and the process continues.

Endpoint

The Endpoint section displays information about the software endpoint found during the resolution process and which processed this request. If the fields in this section are empty it indicates that the resource representation was found in the cache.

Endpoint Class is the Java class providing the endpoint accessor for this request. The function of the endpoint accessor is to return the request resource representation.

Endpoint Module is the NetKernel module hosting the Endpoint Class.

Response

The response section display information about the response to the current request.

Aspects lists all aspects that are associated with the returned resource representation.

Expiry indicates how much time is left before this resource representation expires.

Expiry Dependencies lists all of the resources upon which this resource depends. If any dependent resource expires (and is marked in red), then this resource also expires.

MimeType is the document type associated with the resource representation. For example, this would be text/xml for an XML document.

Creation Cost is the sum of the cost estimates of all sub-requests used to create this response added to the cost of the current accessor's cost estimate.

Usage Cost is an indication of the cost of using this resource representation. This is used for example with stream based resource representations where there is a cost in using ("pulling") the information.

Cacheable flag indicates that the current endpoint accessor has marked this response as an intermediate result. This means that the accessor believes this result will not be valuable by itself but only when used by a parent accessor. This signals to the cache to not save this value. However, a parent accessor's result may still be cached.

Context Sensitive flag indicates that this resource representation's cacheability relates to its super stack context.