org.glowroot.agent.plugin.api.transaction

Interface TransactionService

public interface TransactionService

This is the primary service exposed to plugins. Plugins acquire a TransactionService instance from Agent.getTransactionService(), and they can (and should) cache the TransactionService instance for the life of the jvm to avoid looking it up every time it is needed (which is often).

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.
TimerName	getTimerName(Class<?> adviceClass) Returns the TimerName instance for the specified adviceClass.
boolean	isInTransaction() Returns whether a transaction is already being captured.
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) Set the transaction name that is used for aggregation.
void	setTransactionSlowThreshold(long threshold, TimeUnit unit) Overrides the default slow trace threshold (Configuration > General > Slow trace threshold) for the current transaction.
void	setTransactionType(String transactionType) Set the transaction type that is used for aggregation.
void	setTransactionUser(String user) Sets the user attribute on the transaction.
QueryEntry	startQueryEntry(String queryType, String queryText, long queryExecutionCount, MessageSupplier messageSupplier, TimerName timerName) QueryEntry is a specialized type of TraceEntry that is aggregated by its query text.
QueryEntry	startQueryEntry(String queryType, String queryText, MessageSupplier messageSupplier, TimerName timerName) QueryEntry is a specialized type of TraceEntry that is aggregated by its query text.
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.
TraceEntry	startTransaction(String transactionType, String transactionName, MessageSupplier messageSupplier, TimerName timerName) If there is no active transaction, a new transaction is started.

Method Detail

getTimerName

TimerName getTimerName(Class<?> adviceClass)

Returns the TimerName instance for the specified adviceClass. adviceClass must be a Class with a Pointcut annotation that has a non-empty Pointcut.timerName(). This is how the TimerName is named. The same TimerName is always returned for a given adviceClass. The return value can (and should) be cached by the plugin for the life of the jvm to avoid looking it up every time it is needed (which is often).

startTransaction

TraceEntry startTransaction(String transactionType,
                            String transactionName,
                            MessageSupplier messageSupplier,
                            TimerName timerName)

If there is no active transaction, a new transaction is started. If there is already an active transaction, this method acts the same as startTraceEntry(MessageSupplier, TimerName) (the transaction name and type are not modified on the existing transaction).

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, this method does nothing, and returns a no-op instance of TraceEntry.

startQueryEntry

QueryEntry startQueryEntry(String queryType,
                           String queryText,
                           MessageSupplier messageSupplier,
                           TimerName timerName)

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

startQueryEntry

QueryEntry startQueryEntry(String queryType,
                           String queryText,
                           long queryExecutionCount,
                           MessageSupplier messageSupplier,
                           TimerName timerName)

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

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, this method does nothing, and returns a no-op instance of Timer.

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, this method does nothing.

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, 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, this method does nothing.

setTransactionType

void setTransactionType(@Nullable
                        String transactionType)

Set the transaction type that is used for aggregation. If there is no current transaction, this method does nothing.

setTransactionName

void setTransactionName(@Nullable
                        String transactionName)

Set the transaction name that is used for aggregation. If there is no current transaction, this method does nothing.

setTransactionError

void setTransactionError(@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. 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 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, this method does nothing.

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 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, 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 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, this method does nothing.

setTransactionUser

void setTransactionUser(@Nullable
                        String user)

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 there is no current transaction, 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, this method does nothing. null values are normalized to the empty string.

setTransactionSlowThreshold

void setTransactionSlowThreshold(long threshold,
                                 TimeUnit unit)

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 is called multiple times for a given transaction, the minimum threshold will be used. If there is no current transaction, this method does nothing.

isInTransaction

boolean isInTransaction()

Returns whether a transaction is already being captured. This method has very limited use. It should only be used by top-level pointcuts that define a transaction, and that do not want to create a entry if they are already inside of an existing transaction.