Package org.glowroot.agent.plugin.api

Interface ThreadContext

All Known Subinterfaces:
OptionalThreadContext
public interface ThreadContext

  • Method Details

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

    • startAsyncTraceEntry

      AsyncTraceEntry startAsyncTraceEntry(MessageSupplier messageSupplier, 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.

    • startQueryEntry

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

    • startAsyncQueryEntry

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

    • startServiceCallEntry

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

    • startAsyncServiceCallEntry

      AsyncTraceEntry startAsyncServiceCallEntry(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.

    • createAuxThreadContext

      AuxThreadContext createAuxThreadContext()
      TODO

    • setTransactionAsync

      void setTransactionAsync()
      TODO

    • setTransactionAsyncComplete

      void setTransactionAsyncComplete()
      TODO

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

    • setTransactionType

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

    • setTransactionName

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

    • setTransactionUser

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

    • addTransactionAttribute

      void addTransactionAttribute(String name, 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.

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

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

    • setTransactionError

      void setTransactionError(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(String message, 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.

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

    • addErrorEntry

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

    • trackResourceAcquired

      void trackResourceAcquired(Object resource, boolean withLocationStackTrace)

    • trackResourceReleased

      void trackResourceReleased(Object resource)

    • getServletRequestInfo

      ThreadContext.ServletRequestInfo getServletRequestInfo()

    • setServletRequestInfo

      void setServletRequestInfo(ThreadContext.ServletRequestInfo servletRequestInfo)
      DO NOT USE. This method should only ever be used by the servlet plugin.