Class PerfMark
- java.lang.Object
-
- io.perfmark.PerfMark
-
public final class PerfMark extends java.lang.Object
PerfMark can be automatically enabled by setting the System propertyio.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.
-
-
-
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, orfalse
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 correspondingstartTask(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 correspondingstartTask(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. UselinkOut()
instead.- Returns:
- a no-op link that
-
linkOut
public static Link linkOut()
A link connects between two tasks that start asynchronously. WhenlinkOut()
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 tolinkIn(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 withstartTask(String, Tag)
andstopTask(String, Tag)
. Unlike the two previous two task overloads, the tag provided toattachTag(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
-
-