Module jdk.jfr

Package jdk.jfr

Annotation Type Category

@Target(TYPE)
@Inherited
@Retention(RUNTIME)
public @interface Category

Event annotation, to associate the event type with a category, in the format of a human readable path. The category determines how an event can be presented to the user. Events that lie in the same category will typically be displayed together in graphs and trees. To avoid that durational events overlap in graphical representations, it's important to put overlapping events in separate categories.

Example, let's say you want to monitor image uploads to a web server and that you dedicate a separate thread for each upload. You could then have an event called File Upload which starts when the user uploads a file and ends when the upload is complete. For advanced diagnostics about image uploads you could create more detailed events, let's say Image Read, Image Resize and Image Write. During these detailed events other low level events, for instance Socket Read and File Write could occur.

A visualization that avoid overlaps could look like this:

 -------------------------------------------------------------------
   |                         File Upload                        |
 ------------------------------------------------------------------
   |       Image Read          | Image Resize |   Image Write   |
 ------------------------------------------------------------------
   | Socket Read | Socket Read |              |    File Write   |
 -------------------------------------------------------------------
 

This can be achieved by using the following categories:

Recording options and their purpose.

Event Name	Annotation
File Upload	@Category("Upload")
Image Read	@Category({"Upload", "Image Upload"})
Image Resize	@Category({"Upload", "Image Upload"})
Image Write	@Category({"Upload", "Image Upload"})
Socket Read	@Category("Java Application")
File Write	@Category("Java Application")

File Upload, Image Read and Socket Read happen concurrently (in the same thread), but since the events were put into different categories they do not overlap in the visualization.

The category can also be used to determine how events may be visualized in a tree:

  |- Java Application
  |  |- Socket Read
  |  |- File Write
  |- Upload
     |- File Upload
     |- Image Upload
        |- Image Read
        |- Image Resize
        |- File Write
 

Since:

9

Required Element Summary

Required Elements

Modifier and Type	Required Element	Description
String[]	value	Returns the category names for this annotation, starting with the root.

Element Detail

value

String[] value

Returns the category names for this annotation, starting with the root.

Returns:

the category names