Module jdk.jfr
Package jdk.jfr

Annotation Interface 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 visualization shows overlapping events belonging to a single thread. By assigning the events to different categories they can be visually separated and stacked vertically. 

 13:00:01                                                     13:00:05
 ---------------------------------------------------------------------
  1   |                         File Upload                        |
 ---------------------------------------------------------------------
  2   |       Image Read          | Image Resize |   Image Write   |
 ---------------------------------------------------------------------
  3   | Socket Read | Socket Read |              |    File Write   |
 ---------------------------------------------------------------------
The example can be achieved by using the following categories:
Categories and lanes
Lane Event Name Annotation
1 File Upload @Category("Upload")
2 Image Read @Category({"Upload", "Image Upload"})
2 Image Resize @Category({"Upload", "Image Upload"})
2 Image Write @Category({"Upload", "Image Upload"})
3 Socket Read @Category("Java Application")
3 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