com.yourkit.probes
Class Table

java.lang.Object
  com.yourkit.probes.Table

public class Table
extends java.lang.Object

Data storage table instance.

Extend this class, declaring user columns as its instance fields; each field should be initialized when the constructor of the extending class returns. The fields will be gathered automatically via reflection on first access to the table object. It makes sense to have the table object instance singleton, so declare a static field to hold the table.

See source code of built-in probes to learn more how to use the tables.

Field Summary

static long	LASTING_EVENTS Set this bit in the table mask on table creation if the table rows are intended to describe lasting events, i.e.
static long	MASK_FOR_GENERIC_LASTING_EVENTS Use this bit mask to create a table intended to describe lasting events (read about event kinds...) which can start and end in different thread and/or in different methods.
static long	MASK_FOR_POINT_EVENTS Use this bit mask on table creation, to record uptime, current thread and stack trace when the row is created.
static long	MASK_FOR_SINGLE_METHOD_CALL_LASTING_EVENTS Use this bit mask to create a table intended to describe lasting events (read about event kinds...) which correspond to method calls: the event starts when the monitored method is entered, and ends when the method exits.
static long	RECORD_STACKTRACE_ON_ROW_CLOSE Set this bit in the table mask on table creation to record current stack trace for each row of the table when the row is closed.
static long	RECORD_STACKTRACE_ON_ROW_CREATION Set this bit in the table mask on table creation to record current stack trace for each row of the table when the row is created.
static long	RECORD_THREAD_CPU_TIME Set this bit in the table mask on table creation to automatically measure how much CPU time is been spent in the event's thread since the moment a row has been created and until the moment that row has been closed.
static long	RECORD_THREAD_ON_ROW_CLOSE Set this bit in the table mask on table creation to record current thread for each row of the table when the row is closed.
static long	RECORD_THREAD_ON_ROW_CREATION Set this bit in the table mask on table creation to record current thread for each row of the table when the row is created.

Method Summary

boolean	closeRow(int rowIndex) Invoke this method when a lasting event ends.
int	createRow()
void	setFrequentSamplingThreshold(int wallTimeMs) Do the best to ensure that stack traces are available inside lasting events which run longer than specified number of milliseconds.
void	setMinimumRecordedLastingEventTime(int wallTimeMs) Specifies whether lasting events taking less than the given number of milliseconds should be dropped as the result of their closeRow(int).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LASTING_EVENTS

public static final long LASTING_EVENTS

Set this bit in the table mask on table creation if the table rows are intended to describe lasting events, i.e. those which have start and end, and thus duration in time. If the bit is not set, the table will describe point events, i.e those which correspond to some "facts" which just happen but do not have any duration in time. More about event kinds....

Technically, if this bit is set, high-precision process uptime will be automtically recorded for each row of the table when the row is created, as well as when the row is closed, allowing to determine the event duration. If this bit is not set, process uptime will be recorded only when a row is created, thus it will only be possible to determine the event's position on the timeline, but not the event duration.

If at least one of *_ON_ROW_CLOSE bits is set, LASTING_EVENTS bit must be set too.

See Also:

Constant Field Values

RECORD_THREAD_CPU_TIME

public static final long RECORD_THREAD_CPU_TIME

Set this bit in the table mask on table creation to automatically measure how much CPU time is been spent in the event's thread since the moment a row has been created and until the moment that row has been closed.

If this bit is set, LASTING_EVENTS bit must be set too. Also, the event must be single-threaded (e.g. see MASK_FOR_SINGLE_METHOD_CALL_LASTING_EVENTS, i.e. must start and end in same thread; otherwise CPU time measuring makes no sence.

If this bit is set, RECORD_THREAD_ON_ROW_CREATION bit must be set as well.

See Also:

Constant Field Values

RECORD_THREAD_ON_ROW_CREATION

public static final long RECORD_THREAD_ON_ROW_CREATION

Set this bit in the table mask on table creation to record current thread for each row of the table when the row is created.

See Also:

Constant Field Values

RECORD_THREAD_ON_ROW_CLOSE

public static final long RECORD_THREAD_ON_ROW_CLOSE

Set this bit in the table mask on table creation to record current thread for each row of the table when the row is closed.

If this bit is set, LASTING_EVENTS bit must be set as well.

See Also:

Constant Field Values

RECORD_STACKTRACE_ON_ROW_CREATION

public static final long RECORD_STACKTRACE_ON_ROW_CREATION

Set this bit in the table mask on table creation to record current stack trace for each row of the table when the row is created.

See Also:

Constant Field Values

RECORD_STACKTRACE_ON_ROW_CLOSE

public static final long RECORD_STACKTRACE_ON_ROW_CLOSE

Set this bit in the table mask on table creation to record current stack trace for each row of the table when the row is closed.

If this bit is set, LASTING_EVENTS bit must be set as well.

See Also:

Constant Field Values

MASK_FOR_POINT_EVENTS

public static final long MASK_FOR_POINT_EVENTS

Use this bit mask on table creation, to record uptime, current thread and stack trace when the row is created. Use use this mask if the table is intended to describe point events More about event kinds....

See Also:

Constant Field Values

MASK_FOR_SINGLE_METHOD_CALL_LASTING_EVENTS

public static final long MASK_FOR_SINGLE_METHOD_CALL_LASTING_EVENTS

Use this bit mask to create a table intended to describe lasting events (read about event kinds...) which correspond to method calls: the event starts when the monitored method is entered, and ends when the method exits.

For such events, uptime, CPU time, current thread and stack trace will be recorded when the table row is created, and only uptime and CPU time will be recorded when the row is closed. Thread and stack trace are recorded only once because they are the same on start and end.

See Also:

Constant Field Values

MASK_FOR_GENERIC_LASTING_EVENTS

public static final long MASK_FOR_GENERIC_LASTING_EVENTS

Use this bit mask to create a table intended to describe lasting events (read about event kinds...) which can start and end in different thread and/or in different methods. For example, a file stream can be created in one method, and closed in another method, and even in another thread.

For such events, uptime, CPU time, current thread and stack trace will be recorded when the table row is created, as well as when row is closed.

See Also:

Constant Field Values

Method Detail

createRow

public final int createRow()

closeRow

public final boolean closeRow(int rowIndex)

Invoke this method when a lasting event ends.

Returns:

false if row has been dropped because it was shorter than the threshold set by setMinimumRecordedLastingEventTime(int), or table row count threshold has been reached; true if row actually exists in the table. This return value can be used for optimization purposes: if row is dropped, you can skip setting its column values.

setMinimumRecordedLastingEventTime

public final void setMinimumRecordedLastingEventTime(int wallTimeMs)

Specifies whether lasting events taking less than the given number of milliseconds should be dropped as the result of their closeRow(int). This helps to limit the number of rows in the table in case when there are very many events of some kind, but only few of them deserve attention. Otherwise, recording all events would waste resources by storing non-useful information. UI event queue is a good example of such events: there are thousands of them, but only longest should be examined to investigate irresponsible UI.

Parameters:

wallTimeMs - specifies the number of milliseconds that must pass to ensure the events are retained in the table; specify 0 to retain all events (default behavior)

setFrequentSamplingThreshold

public final void setFrequentSamplingThreshold(int wallTimeMs)

Do the best to ensure that stack traces are available inside lasting events which run longer than specified number of milliseconds. The stack traces help to analyse what is happening in each of such events. If wallTimeMs milliseconds pass after createRow() and until closeRow(int) is called, stack traces are collected more frequently. Stack trace collection frequency returns to normal after all rows for which frequent collection has been activated are closed.

Parameters:

wallTimeMs - specifies the number of milliseconds that must pass to start more frequent stack trace collection; specify -1 to disable changing of stack trace collection frequency depending on event duration (default behavior)