3 Guidelines for Naming and Labeling Events
You should name and label all of your events by setting the annotations @Name and @Label.
Guidelines for Naming Events
Use the following format for naming your events, where
www.example.com
is the domain of your organization and
Name
is the name of your event
class:
com.example.Name
When naming your event class, omit the word "Event."
By default, an event gets its name from its fully qualified class name.
For example, in the example SetMetadataSample.java
(see Event Metadata), the default name of the event Hello
is
frexamples.SetMetadataSample$Hello
.
This works well for experimentation, but avoid omitting the @Name annotation for production code. You might have to refactor your source code and move the event class to a different package. If you haven't specified the event's name with the @Name annotation, then refactoring an event class can break code or settings files that configure the event. It can also break code that parses recording files that use the default name to identify an event.
The fully qualified class name may also contain redundant or
unnecessary strings such as jfr
, internal
,
events
, or Events
that you should omit.
An event name should be short but not so short that it clashes with other
organizations or products. The name should be easy to understand for users who want
to configure the event. This is especially true if the event is part of a framework
or library that is meant to be used by others. It's usually sufficient to put all
the events for a library or product in the same namespace. For example, all the
events for OpenJDK are in the jdk
namespace. There are no
sub-namespaces for hotspot
, gc
, or
compiler
as this would just complicate things. However, it's
possible to divide events into categories with the @Category annotation, which you can freely change without
disruption.
Guidelines for Labeling Events
For labels, use headline-style capitalization: Capitalize the first and last words and all nouns, pronouns, adjectives, verbs and adverbs. Do not include ending punctuation. As with event names, omit the word "Event." Note that you shouldn't use @Label as an identifier; use the @Name annotation instead.
Use labels to display events in user interfaces such as a custom visualization tool. For example, JDK Mission Control's Event Browser uses the label to display events in its Event Types Tree.