org.glowroot.agent.plugin.api

Interface TraceEntry

All Known Subinterfaces:

AsyncQueryEntry, AsyncTraceEntry, QueryEntry

public interface TraceEntry

See ThreadContext.startTraceEntry(MessageSupplier, TimerName) for how to create and use TraceEntry instances.

Method Summary

Modifier and Type	Method and Description
void	end() End the entry.
void	endWithError(String message) End the entry and mark the trace entry as an error with the specified throwable.
void	endWithError(String message, Throwable t) End the entry and add the specified errorMessage to the entry.
void	endWithError(Throwable t) End the entry and mark the trace entry as an error with the specified throwable.
void	endWithInfo(Throwable t) This method is the same as endWithError(Throwable), except that it won't escalate a dummy entry into a real entry.
void	endWithStackTrace(long threshold, TimeUnit unit) End the entry and capture a stack trace if its total time exceeds the specified threshold.
Object	getMessageSupplier() Returns the message supplier that was supplied when the TraceEntry was created.

Method Detail

end

void end()

End the entry.

endWithError

void endWithError(@Nullable
                  String message)

End the entry and mark the trace entry as an error with the specified throwable. A stack trace is captured and displayed in the UI as a location stack trace (as opposed to an exception stack trace), similar to endWithStackTrace(long, TimeUnit). Unless this is the root trace entry in which case no location stack trace is captured / displayed (since location stack trace is typically not mysterious for root trace entries). If this is the root entry, then the error flag on the transaction is set. In case the transaction has accumulated maxTraceEntriesPerTransaction entries and this is a dummy entry, then this dummy entry is escalated into a real entry. A hard cap ( maxTraceEntriesPerTransaction * 2) on the total number of (real) entries is applied when escalating dummy entries to real entries.

endWithError

void endWithError(@Nullable
                  String message,
                  Throwable t)

End the entry and add the specified errorMessage to the entry. If message is empty or null, then the error message text is captured from Throwable#getMessage(). If this is the root entry, then the error flag on the transaction is set. In case the transaction has accumulated maxTraceEntriesPerTransaction entries and this is a dummy entry, then this dummy entry is escalated into a real entry. A hard cap ( maxTraceEntriesPerTransaction * 2) on the total number of (real) entries is applied when escalating dummy entries to real entries.

endWithError

void endWithError(Throwable t)

End the entry and mark the trace entry as an error with the specified throwable. The error message text is captured from Throwable#getMessage(). If this is the root entry, then the error flag on the transaction is set. In case the transaction has accumulated maxTraceEntriesPerTransaction entries and this is a dummy entry, then this dummy entry is escalated into a real entry. A hard cap ( maxTraceEntriesPerTransaction * 2) on the total number of (real) entries is applied when escalating dummy entries to real entries.

endWithInfo

void endWithInfo(Throwable t)

This method is the same as endWithError(Throwable), except that it won't escalate a dummy entry into a real entry.

endWithStackTrace

void endWithStackTrace(long threshold,
                       TimeUnit unit)

End the entry and capture a stack trace if its total time exceeds the specified threshold. In case the trace has accumulated maxTraceEntriesPerTransaction entries and this is a dummy entry and its total time exceeds the specified threshold, then this dummy entry is escalated into a real entry. A hard cap (maxTraceEntriesPerTransaction * 2) on the total number of (real) entries is applied when escalating dummy entries to real entries. This is a no-op for async trace entries (those created by ThreadContext.startAsyncTraceEntry(MessageSupplier, TimerName) and ThreadContext.startAsyncQueryEntry(String, String, QueryMessageSupplier, TimerName)). This is because async trace entries are used when their end is performed by a different thread, and so a stack trace at that time does not point to the code which executed triggered the trace entry creation.

getMessageSupplier

@Nullable
Object getMessageSupplier()

Returns the message supplier that was supplied when the TraceEntry was created. This can be useful (for example) to retrieve the message supplier in @OnReturn so that the return value can be added to the message produced by the MessageSupplier. This returns the message supplier even if the trace has accumulated maxTraceEntriesPerTransaction entries and this is a dummy entry. Under some error conditions this can return null.