The WebSphere® Real Time perspective provides predefined views, such as class loading or JIT compilation. You can also create, edit, and delete your own custom views, to analyze other data from a WebSphere Real Time JVM. You can create a view for a particular method or selected trace points, and you can combine two views into one.
About this task
The views are defined in a custom view definition file. The location of this file is set in the perspective preferences. For more information about this setting, see Setting preferences for the WebSphere Real Time perspective.
You can create a custom view in the following ways:
- Use a Java™ method descriptor
Use this option when you want to create a view from trace information for a particular method. This type of view can be useful when you want to monitor business methods for deterministic behavior. The view is based on the entry and exit method traces that are created when the method is called.
- Choose trace points from the J9TraceFormat.dat file
The
J9TraceFormat.dat file contains trace points that are used for debugging applications, for example, function entry and exit points. The standard views in Health Center are based on some of these trace points. If you want to analyze different trace points, create a custom view by using this option. For example, you can monitor the deterministic behavior of socket writes by using the following trace points in the
J9TraceFormat.dat file:
j9prt 564 Entry Trc_PRT_sock_j9sock_write_Entry
j9prt 565 Exit Trc_PRT_sock_j9sock_write_Exit
You usually use Entry and Exit trace points to plot data. However, you can also use trace points of type Info, by changing the event type of those trace points to Entry or Exit.
The entry and exit times are shown on the graph as hover information when you move your mouse over the data point. Some Info trace points contain parameters, such as the name of the class or stack that is involved in the operation. You can specify that these trace points are used to generate the hover information that is shown on the graph.
For more information about the J9TraceFormat.dat file, see the documentation for your version of IBM® SDK and Runtime Environment Java Technology Edition. For example
Determining the tracepoint ID of a tracepoint in the Version 7 documentation.
- Combine two existing views
Use this option when you want to examine the activity of threads from multiple components at the same time. For example, your application might have a method, method_1, which calls another method, method_2. You can analyze outlier events for each method in a separate view. However, an outlier that is visible in the view of method_1 might be caused by method_2. The cause of the outlier is easier to find if both views are visible at the same time.
When you create the view, you choose a primary and a secondary view. The Plot tab shows graphs for both the primary and secondary views. The graph for the primary view shows outlier events, in numbered circles, that are caused by events in the secondary view. The x-axis is the same for both views, but the y-axis might be different.
The Summary, Histogram, and Analysis and Recommendations tabs apply only to the primary view. The Analysis and Recommendations tab includes the percentage of trace points where the same thread is processing events in both views at the same time.
Procedure
- Optional: If you want to create a custom view by using trace points, ensure that information about those trace points is collected. You can enable trace points at run time by clicking Trace Settings... in the Monitored JVM menu. For more information, see Collecting and saving binary JVM trace data (Java applications only).
- In the WebSphere Real Time perspective, click Add custom view. The " WebSphere Real Time: custom view management" wizard opens.
- If you have not specified a custom view definition file in the WebSphere Real Time preferences, specify one in the first page of the wizard, then click Next. Your custom views will be defined in this file so that they are still available when you restart Health Center.
- Select the type of custom view to create, and click Next.
- Optional: If you selected Create a view using a Java method descriptor, complete the following steps:
- Add a view name and description.
- Add a Java method descriptor. Use the following format:
package/subpackage/class.method[*]
For
example java/util/LinkedList.add.
Use the asterisk (*) as a wildcard character, to match multiple methods. For example java/util/LinkedList.*.
- Click Finish to create the view.
- Optional: If you selected Create a view by choosing trace points from J9TraceFormat.dat file, complete the following steps:
- Click Browse, then select your J9TraceFormat.dat file. The J9TraceFormat.dat file is in the jre/lib directory in your Java installation. The trace points from the file are displayed.
- Select two or more trace points from the list, by pressing and holding the Control key while you select, then click Next.
- In the "Define view" page, add a view name and description.
- The "Define view" page also lists the trace points that you selected earlier. The details for each trace point include the type, the number of parameters, and the parameter that is used to generate hover text in the plot graph. If required, select a trace point and use the following fields to update the displayed details for that trace point:
- Format text
This field displays the format text template from the J9TraceFormat.dat file. The Java trace formatting tool uses this template to format the trace point into a readable form. For example, the text template for the j9vm Trc_VM_terminateRemainingThreads_Daemon trace point is " Daemon thread still running: %p". Use the text in this field to see if there are any information parameters, such as %p in the previous example, which you can use to add hover information to the graph.
- Event type
Entry and Exit trace points are used to plot the data on the graph. If you want to use trace points of type Info to plot the data, use this field to change the event type from Info to Entry or Exit. Select an event type and click
Update entry to update the list of trace points. For example, you can use the following Info trace points to plot when an object monitor is inflated (created) and deflated, by changing the type of the first trace point to Entry, and the type of the second trace point to Exit.
j9vm 435 Info 4 NONE Trc_VM_objectMonitorInflated
j9vm 436 Info 4 NONE Trc_VM_objectMonitorDeflated
- Information parameter
Some trace points have parameters in their format text. You can use these parameters to generate hover information on the plot graph for this view. Select a parameter, then click Update entry to set the parameter. If you do not select an information parameter, the hover information shows the entry and exit time for the trace points that you selected.
For example, you might select the j9vm Trc_freeStacks trace points from the
J9TraceFormat.dat file. The "Define view" page of the wizard shows that there is an Entry trace point, an Exit trace point, and an Info trace point that has two parameters:
j9vm 64 Entry 0 NONE Trc_VM_freeStacks_Entry
j9vm 65 Info 2 NONE Trc_VM_freeStacks_Free
j9vm 66 Exit 0 NONE Trc_VM_freeStacks_Exit
If you
select the Info trace point, the
Format text field shows the format text template for that trace point, which includes the two parameters %p and %zu:
" Freeing stack %p (size %zu)"
If
you set parameter 0 (%p) as the information parameter, the hover information
on the plot shows the stack that is being freed.
- Click Finish to create the view.
- Optional: If you selected Create a view which shows two plots on the same graph, complete the following steps:
- Add a view name and description.
- Choose a primary view, and a different secondary view, from the lists provided, then click Finish.
Results
When the wizard finishes, the view is added to the perspective and is available immediately.
Note: A view shows data only when the required trace settings are provided for a target JVM.
What to do next
You can edit or delete existing custom views.
To edit a custom view, select the view in the Select view list, then click Edit view to start the wizard. Modify the fields as required. You cannot modify the name of a view.
To delete a custom view, select the view in the Select view list, then click Delete view. The view is deleted. Any data that is associated with the view is also deleted.
The Edit view and Delete view buttons are enabled only when a custom view is selected in the Select view list.