Package 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
    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
    endWithLocationStackTrace(long threshold, TimeUnit unit)
    End the entry and capture a stack trace if its total time exceeds the specified threshold.
    Timer
    extend()
    Example of query and subsequent iterating over results which goes back to database and pulls more results.
    Object
    getMessageSupplier()
    Returns the message supplier that was supplied when the TraceEntry was created.

  • Method Details

    • end

      void end()
      End the entry.

    • endWithLocationStackTrace

      void endWithLocationStackTrace(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.

    • 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.

    • endWithError

      void endWithError(String message)
      End the entry and mark the trace entry as an error with the specified throwable. 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(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.

    • 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.

    • extend

      Timer extend()
      Example of query and subsequent iterating over results which goes back to database and pulls more results. Important note for async trace entries (those created by ThreadContext.startAsyncTraceEntry(MessageSupplier, TimerName) and ThreadContext.startAsyncQueryEntry(String, String, QueryMessageSupplier, TimerName)): this method should not be used by a thread other than the one that created the async trace entry.

    • getMessageSupplier

      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.