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 is presented to the user. Events that are in the same category are typically displayed together in graphs and trees. To avoid the overlap of durational events in graphical representations, overlapping events must be in separate categories.

For example, to monitor image uploads to a web server with a separate thread for each upload, an event called File Upload starts when the user uploads a file and ends when the upload is complete. For advanced diagnostics about image uploads, more detailed events are created (for example, Image Read, Image Resize, and Image Write). During these detailed events. other low level-events could occur (for example, Socket Read and File Write).

The following example shows a visualization that avoids overlaps: 

 -------------------------------------------------------------------
   |                         File Upload                        |
 ------------------------------------------------------------------
   |       Image Read          | Image Resize |   Image Write   |
 ------------------------------------------------------------------
   | Socket Read | Socket Read |              |    File Write   |
 -------------------------------------------------------------------
The example 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")

The File Upload, Image Read, and Socket Read events happen concurrently (in the same thread), but the events are in different categories so they do not overlap in the visualization.

The following examples shows how the category is used to determine how events are 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 Details

    • value

      String[] value
      Returns the category names for this annotation, starting with the root.
      Returns:
      the category names