Package io.perfmark

Class PerfMark


  • public final class PerfMark
    extends java.lang.Object
    PerfMark can be automatically enabled by setting the System property io.perfmark.PerfMark.startEnabled to true.
    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static void attachTag​(Tag tag)
      Attaches an additional tag to the current active task.
      static Tag createTag()
      Creates a tag with no name or numeric identifier.
      static Tag createTag​(long id)
      Creates a tag with no name.
      static Tag createTag​(java.lang.String name)
      Creates a tag with no numeric identifier.
      static Tag createTag​(java.lang.String name, long id)
      Creates a tag with both a name and a numeric identifier.
      static void event​(java.lang.String eventName)
      Marks an event.
      static void event​(java.lang.String eventName, Tag tag)
      Marks an event.
      static Link link()
      Deprecated.
      static void linkIn​(Link link)
      Associate this link with the most recently started task.
      static Link linkOut()
      A link connects between two tasks that start asynchronously.
      static void setEnabled​(boolean value)
      Turns on or off PerfMark recording.
      static void startTask​(java.lang.String taskName)
      Marks the beginning of a task.
      static void startTask​(java.lang.String taskName, Tag tag)
      Marks the beginning of a task.
      static void stopTask​(java.lang.String taskName)
      Marks the end of a task.
      static void stopTask​(java.lang.String taskName, Tag tag)
      Marks the end of a task.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • setEnabled

        public static void setEnabled​(boolean value)
        Turns on or off PerfMark recording. Don't call this method too frequently; while neither on nor off have very high overhead, transitioning between the two may be slow.
        Parameters:
        value - true to enable PerfMark recording, or false to disable it.
      • startTask

        public static void startTask​(java.lang.String taskName,
                                     Tag tag)
        Marks the beginning of a task. If PerfMark is disabled, this method is a no-op. The name of the task should be a runtime-time constant, usually a string literal. Tasks with the same name can be grouped together for analysis later, so avoid using too many unique task names.

        The tag is a run-time identifier for the task. It represents the dynamic part of the task, while the task name is the constant part of the task. While not always enforced, tags should not be null.

        Parameters:
        taskName - the name of the task.
        tag - a user provided tag for the task.
      • startTask

        public static void startTask​(java.lang.String taskName)
        Marks the beginning of a task. If PerfMark is disabled, this method is a no-op. The name of the task should be a runtime-time constant, usually a string literal. Tasks with the same name can be grouped together for analysis later, so avoid using too many unique task names.
        Parameters:
        taskName - the name of the task.
      • event

        public static void event​(java.lang.String eventName,
                                 Tag tag)
        Marks an event. Events are logically both a task start and a task end. Events have no duration associated. Events still represent the instant something occurs. If PerfMark is disabled, this method is a no-op.

        The tag is a run-time identifier for the event. It represents the dynamic part of the event, while the event name is the constant part of the event. While not always enforced, tags should not be null.

        Parameters:
        eventName - the name of the event.
        tag - a user provided tag for the event.
      • event

        public static void event​(java.lang.String eventName)
        Marks an event. Events are logically both a task start and a task end. Events have no duration associated. Events still represent the instant something occurs. If PerfMark is disabled, this method is a no-op.
        Parameters:
        eventName - the name of the event.
      • stopTask

        public static void stopTask​(java.lang.String taskName,
                                    Tag tag)
        Marks the end of a task. If PerfMark is disabled, this method is a no-op. The task name and tag should match the ones provided to the corresponding startTask(String, Tag). If the task name or tag do not match, the implementation may not be able to associate the starting and stopping of a single task. The name of the task should be a runtime-time constant, usually a string literal.

        It is important that stopTask(java.lang.String, io.perfmark.Tag) always be called after starting a task, even in case of exceptions. Failing to do so may result in corrupted results.

        Parameters:
        taskName - the name of the task being ended.
        tag - the tag of the task being ended.
      • stopTask

        public static void stopTask​(java.lang.String taskName)
        Marks the end of a task. If PerfMark is disabled, this method is a no-op. The task name should match the ones provided to the corresponding startTask(String). If the task name or tag do not match, the implementation may not be able to associate the starting and stopping of a single task. The name of the task should be a runtime-time constant, usually a string literal.

        It is important that stopTask(java.lang.String, io.perfmark.Tag) always be called after starting a task, even in case of exceptions. Failing to do so may result in corrupted results.

        Parameters:
        taskName - the name of the task being ended.
      • createTag

        public static Tag createTag()
        Creates a tag with no name or numeric identifier. The returned instance is different based on if PerfMark is enabled or not.

        This method is seldomly useful; users should generally prefer to use the overloads of methods that don't need a tag. An empty tag may be useful though when the tag of a group of tasks may change over time.

        Returns:
        a Tag that has no name or id.
      • createTag

        public static Tag createTag​(long id)
        Creates a tag with no name. The returned instance is different based on if PerfMark is enabled or not. The provided id does not have to be globally unique, but is instead meant to give context to a task.
        Parameters:
        id - a user provided identifier for this Tag.
        Returns:
        a Tag that has no name.
      • createTag

        public static Tag createTag​(java.lang.String name)
        Creates a tag with no numeric identifier. The returned instance is different based on if PerfMark is enabled or not. The provided name does not have to be globally unique, but is instead meant to give context to a task.
        Parameters:
        name - a user provided name for this Tag.
        Returns:
        a Tag that has no numeric identifier.
      • createTag

        public static Tag createTag​(java.lang.String name,
                                    long id)
        Creates a tag with both a name and a numeric identifier. The returned instance is different based on if PerfMark is enabled or not. Neither the provided name nor id has to be globally unique, but are instead meant to give context to a task.
        Parameters:
        id - a user provided identifier for this Tag.
        name - a user provided name for this Tag.
        Returns:
        a Tag that has both a name and id.
      • link

        @Deprecated
        public static Link link()
        Deprecated.
        DO NOT CALL, no longer implemented. Use linkOut() instead.
        Returns:
        a no-op link that
      • linkOut

        public static Link linkOut()
        A link connects between two tasks that start asynchronously. When linkOut() is called, an association between the most recently started task and a yet-to-be named task on another thread, is created. Links are a one-to-many relationship. A single started task can have multiple associated tasks on other threads.
        Returns:
        A Link to be used in other tasks.
        Since:
        0.17.0
      • linkIn

        public static void linkIn​(Link link)
        Associate this link with the most recently started task. There may be at most one inbound linkage per task: the first call to linkIn(io.perfmark.Link) decides which outbound task is the origin.
        Parameters:
        link - a link created inside of another task.
        Since:
        0.17.0
      • attachTag

        public static void attachTag​(Tag tag)
        Attaches an additional tag to the current active task. The tag provided is independent of the tag used with startTask(String, Tag) and stopTask(String, Tag). Unlike the two previous two task overloads, the tag provided to attachTag(Tag) does not have to match any other tags in use. This method is useful for when you have the tag information after the task is started.

        Here are some example usages:

        Recording the amount of work done in a task:

           PerfMark.startTask("read");
           byte[] data = file.read();
           PerfMark.attachTag(PerfMark.createTag("bytes read", data.length));
           PerfMark.stopTask("read");
         

        Recording a tag which may be absent on an exception:

           Socket s;
           Tag remoteTag = PerfMark.createTag(remoteAddress.toString());
           PerfMark.startTask("connect", remoteTag);
           try {
             s = connect(remoteAddress);
             PerfMark.attachTag(PerfMark.createTag(s.getLocalAddress().toString());
           } finally {
             PerfMark.stopTask("connect", remoteTag);
           }
         
        Parameters:
        tag - the Tag to attach.
        Since:
        0.18.0