org.glowroot.agent.plugin.api

Interface ThreadContext

All Known Subinterfaces:

OptionalThreadContext

public interface ThreadContext

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ThreadContext.Priority

Method Summary

Modifier and Type	Method and Description
void	addErrorEntry(String message) Adds a trace entry with the specified error message and total time of zero.
void	addErrorEntry(String message, Throwable t) Adds a trace entry with the specified error message and total time of zero.
void	addErrorEntry(Throwable t) Adds a trace entry with the specified error message and total time of zero.
void	addTransactionAttribute(String name, String value) Adds an attribute on the current transaction with the specified name and value.
AuxThreadContext	createAuxThreadContext() TODO
MessageSupplier	getServletMessageSupplier() Special purpose method.
void	setServletMessageSupplier(MessageSupplier messageSupplier) Special purpose method.
void	setTransactionAsync() TODO
void	setTransactionAsyncComplete() TODO
void	setTransactionError(String message) Marks the transaction as an error with the given message.
void	setTransactionError(String message, Throwable t) Marks the transaction as an error with the given message.
void	setTransactionError(Throwable t) Marks the transaction as an error with the given message.
void	setTransactionName(String transactionName, int priority) Set the transaction name that is used for aggregation.
void	setTransactionOuter() This should be used in very limited circumstances.
void	setTransactionSlowThreshold(long threshold, TimeUnit unit, int priority) Overrides the default slow trace threshold (Configuration > General > Slow trace threshold) for the current transaction.
void	setTransactionType(String transactionType, int priority) Set the transaction type that is used for aggregation.
void	setTransactionUser(String user, int priority) Sets the user attribute on the transaction.
AsyncQueryEntry	startAsyncQueryEntry(String queryType, String queryText, QueryMessageSupplier queryMessageSupplier, TimerName timerName)
AsyncTraceEntry	startAsyncServiceCallEntry(String type, String text, MessageSupplier messageSupplier, TimerName timerName)
AsyncTraceEntry	startAsyncTraceEntry(MessageSupplier messageSupplier, TimerName timerName)
QueryEntry	startQueryEntry(String queryType, String queryText, long queryExecutionCount, QueryMessageSupplier queryMessageSupplier, TimerName timerName)
QueryEntry	startQueryEntry(String queryType, String queryText, QueryMessageSupplier queryMessageSupplier, TimerName timerName) QueryEntry is a specialized type of TraceEntry that is aggregated by its query text.
TraceEntry	startServiceCallEntry(String type, String text, MessageSupplier messageSupplier, TimerName timerName)
Timer	startTimer(TimerName timerName) Starts a timer for the specified timer name.
TraceEntry	startTraceEntry(MessageSupplier messageSupplier, TimerName timerName) Creates and starts a trace entry with the given messageSupplier.

Method Detail

addErrorEntry

void addErrorEntry(@Nullable
                   String message)

Adds a trace entry with the specified error message and total time of zero. It does not set the error attribute on the transaction, which must be done with setTransactionError(java.lang.Throwable) or with endWithError on the root entry. Since there is no throwable passed to this variant, a stack trace is captured and displayed in the UI as a location stack trace (as opposed to an exception stack trace), similar to TraceEntry.endWithStackTrace(long, TimeUnit). This method bypasses the regular maxTraceEntriesPerTransaction check so that errors after maxTraceEntriesPerTransaction will still be included in the trace. A hard cap ( maxTraceEntriesPerTransaction * 2) on the total number of entries is still applied, after which this method does nothing. If there is no current transaction then this method does nothing.

addErrorEntry

void addErrorEntry(@Nullable
                   String message,
                   Throwable t)

Adds a trace entry with the specified error message and total time of zero. It does not set the error attribute on the transaction, which must be done with setTransactionError(java.lang.Throwable) or with endWithError on the root entry. If message is null, then the error message is captured from Throwable#getMessage(). This method bypasses the regular maxTraceEntriesPerTransaction check so that errors after maxTraceEntriesPerTransaction will still be included in the trace. A hard cap ( maxTraceEntriesPerTransaction * 2) on the total number of entries is still applied, after which this method does nothing. If there is no current transaction then this method does nothing.

addErrorEntry

void addErrorEntry(Throwable t)

Adds a trace entry with the specified error message and total time of zero. It does not set the error attribute on the transaction, which must be done with setTransactionError(java.lang.Throwable) or with endWithError on the root entry. The error message text is captured from Throwable#getMessage(). This method bypasses the regular maxTraceEntriesPerTransaction check so that errors after maxTraceEntriesPerTransaction will still be included in the trace. A hard cap ( maxTraceEntriesPerTransaction * 2) on the total number of entries is still applied, after which this method does nothing. If there is no current transaction then this method does nothing.

addTransactionAttribute

void addTransactionAttribute(String name,
                             @Nullable
                             String value)

Adds an attribute on the current transaction with the specified name and value. A transaction's attributes are displayed when viewing a trace on the trace explorer page. Subsequent calls to this method with the same name on the same transaction will add an additional attribute if there is not already an attribute with the same name and value. If there is no current transaction then this method does nothing. null values are normalized to the empty string.

createAuxThreadContext

AuxThreadContext createAuxThreadContext()

TODO

getServletMessageSupplier

@Nullable
MessageSupplier getServletMessageSupplier()

Special purpose method.

setServletMessageSupplier

void setServletMessageSupplier(@Nullable
                               MessageSupplier messageSupplier)

Special purpose method.

setTransactionAsync

void setTransactionAsync()

TODO

setTransactionAsyncComplete

void setTransactionAsyncComplete()

TODO

setTransactionError

void setTransactionError(@Nullable
                         String message)

Marks the transaction as an error with the given message. Normally transactions are only marked as an error if endWithError is called on the root entry. This method can be used to mark the entire transaction as an error from a nested entry. This should be used sparingly. Normally, entries should only mark themselves (using endWithError), and let the root entry determine if the transaction as a whole should be marked as an error. E.g., this method is called from the logger plugin, to mark the entire transaction as an error if an error is logged through one of the supported logger APIs. If this method is called multiple times within a single transaction, only the first call has any effect, and subsequent calls are ignored. If there is no current transaction then this method does nothing.

setTransactionError

void setTransactionError(@Nullable
                         String message,
                         @Nullable
                         Throwable t)

Marks the transaction as an error with the given message. Normally transactions are only marked as an error if endWithError is called on the root entry. This method can be used to mark the entire transaction as an error from a nested entry. If message is empty or null, then the error message text is captured from Throwable#getMessage(). This should be used sparingly. Normally, entries should only mark themselves (using endWithError), and let the root entry determine if the transaction as a whole should be marked as an error. E.g., this method is called from the logger plugin, to mark the entire transaction as an error if an error is logged through one of the supported logger APIs. If this method is called multiple times within a single transaction, only the first call has any effect, and subsequent calls are ignored. If there is no current transaction then this method does nothing.

setTransactionError

void setTransactionError(Throwable t)

Marks the transaction as an error with the given message. Normally transactions are only marked as an error if endWithError is called on the root entry. This method can be used to mark the entire transaction as an error from a nested entry. The error message text is captured from Throwable#getMessage(). This should be used sparingly. Normally, entries should only mark themselves (using endWithError), and let the root entry determine if the transaction as a whole should be marked as an error. E.g., this method is called from the logger plugin, to mark the entire transaction as an error if an error is logged through one of the supported logger APIs. If this method is called multiple times within a single transaction, only the first call has any effect, and subsequent calls are ignored. If there is no current transaction then this method does nothing.

setTransactionName

void setTransactionName(@Nullable
                        String transactionName,
                        int priority)

Set the transaction name that is used for aggregation. Calling this method with a non-null non-empty value overrides the transaction name set in OptionalThreadContext.startTransaction(String, String, MessageSupplier, TimerName). If this method is called multiple times within a single transaction, the highest priority non-null non-empty value wins, and priority ties go to the first caller. See ThreadContext.Priority for common priority values. If there is no current transaction then this method does nothing.

setTransactionOuter

void setTransactionOuter()

This should be used in very limited circumstances. E.g. a really long "outer" transaction that processes thousands of objects, where it is useful to track the processing details per object as separate transactions, but also useful to track the overarching long "outer" transaction. Once a transaction is marked as an outer transaction, then OptionalThreadContext.startTransaction(String, String, MessageSupplier, TimerName) will start a new "inner" transaction. To start a new "inner" transaction, the active "outer" transaction is unbound from the thread, and the new "inner" transaction is started and bound to the thread. When the "inner" transaction ends, the previously active "outer" transaction is bound back to the thread. If there is no current transaction then this method does nothing.

setTransactionSlowThreshold

void setTransactionSlowThreshold(long threshold,
                                 TimeUnit unit,
                                 int priority)

Overrides the default slow trace threshold (Configuration > General > Slow trace threshold) for the current transaction. This can be used to store particular traces at a lower or higher threshold than the general threshold. If this method is called multiple times within a single transaction, the highest priority non-null non-empty value wins, and priority ties go to the first caller. See ThreadContext.Priority for common priority values. If there is no current transaction then this method does nothing.

setTransactionType

void setTransactionType(@Nullable
                        String transactionType,
                        int priority)

Set the transaction type that is used for aggregation. Calling this method with a non-null non-empty value overrides the transaction type set in OptionalThreadContext.startTransaction(String, String, MessageSupplier, TimerName). If this method is called multiple times within a single transaction, the highest priority non-null non-empty value wins, and priority ties go to the first caller. See ThreadContext.Priority for common priority values. If there is no current transaction then this method does nothing.

setTransactionUser

void setTransactionUser(@Nullable
                        String user,
                        int priority)

Sets the user attribute on the transaction. This attribute is shared across all plugins, and is generally set by the plugin that initiated the trace, but can be set by other plugins if needed. The user is used in a few ways:

• The user is displayed when viewing a trace on the trace explorer page
• Traces can be filtered by their user on the trace explorer page
• Glowroot can be configured (using the configuration page) to capture traces for a specific user using a lower threshold than normal (e.g. threshold=0 to capture all requests for a specific user)
• Glowroot can be configured (using the configuration page) to perform profiling on all transactions for a specific user

If profiling is enabled for a specific user, this is activated (if the user matches) at the time that this method is called, so it is best to call this method early in the transaction. If this method is called multiple times within a single transaction, the highest priority non-null non-empty value wins, and priority ties go to the first caller. See ThreadContext.Priority for common priority values. If there is no current transaction then this method does nothing.

startAsyncQueryEntry

AsyncQueryEntry startAsyncQueryEntry(String queryType,
                                     String queryText,
                                     QueryMessageSupplier queryMessageSupplier,
                                     TimerName timerName)

startAsyncServiceCallEntry

AsyncTraceEntry startAsyncServiceCallEntry(String type,
                                           String text,
                                           MessageSupplier messageSupplier,
                                           TimerName timerName)

startAsyncTraceEntry

AsyncTraceEntry startAsyncTraceEntry(MessageSupplier messageSupplier,
                                     TimerName timerName)

startQueryEntry

QueryEntry startQueryEntry(String queryType,
                           String queryText,
                           long queryExecutionCount,
                           QueryMessageSupplier queryMessageSupplier,
                           TimerName timerName)

startQueryEntry

QueryEntry startQueryEntry(String queryType,
                           String queryText,
                           QueryMessageSupplier queryMessageSupplier,
                           TimerName timerName)

QueryEntry is a specialized type of TraceEntry that is aggregated by its query text.

startServiceCallEntry

TraceEntry startServiceCallEntry(String type,
                                 String text,
                                 MessageSupplier messageSupplier,
                                 TimerName timerName)

startTimer

Timer startTimer(TimerName timerName)

Starts a timer for the specified timer name. If a timer is already running for the specified timer name, it will keep an internal counter of the number of starts, and it will only end the timer after the corresponding number of ends. If there is no current transaction then this method does nothing, and returns a no-op instance of Timer.

startTraceEntry

TraceEntry startTraceEntry(MessageSupplier messageSupplier,
                           TimerName timerName)

Creates and starts a trace entry with the given messageSupplier. A timer for the specified timer name is also started. Since entries can be expensive in great quantities, there is a maxTraceEntriesPerTransaction property on the configuration page to limit the number of entries captured for any given trace. Once a trace has accumulated maxTraceEntriesPerTransaction entries, this method doesn't add new entries to the trace, but instead returns a dummy entry. A timer for the specified timer name is still started, since timers are very cheap, even in great quantities. The dummy entry adheres to the TraceEntry contract and returns the specified MessageSupplier in response to TraceEntry.getMessageSupplier(). Calling TraceEntry.end() on the dummy entry ends the timer. If endWithError is called on the dummy entry, then the dummy entry will be escalated to a real entry. If TraceEntry.endWithStackTrace(long, TimeUnit) is called on the dummy entry and the dummy entry total time exceeds the specified threshold, then the dummy entry will be escalated to a real entry. If endWithError is called on the dummy entry, then the dummy entry will be escalated to a real entry. A hard cap ( maxTraceEntriesPerTransaction * 2) on the total number of (real) entries is applied when escalating dummy entries to real entries. If there is no current transaction then this method does nothing, and returns a no-op instance of TraceEntry.