org.glowroot.api

Class PluginServices

java.lang.Object

org.glowroot.api.PluginServices

public abstract class PluginServices
extends Object

This is the primary service exposed to plugins. Plugins acquire a PluginServices instance from get(String), and they can (and should) cache the PluginServices instance for the life of the jvm to avoid looking it up every time it is needed (which is often). Here is a basic example of how to use PluginServices to create a plugin that captures calls to Spring validators:

 @Aspect
 public class SpringAspect {
 
     private static final PluginServices pluginServices = PluginServices.get("spring");
 
     @Pointcut(className = "org.springframework.validation.Validator",
             methodName = "validate", methodParameterTypes = {".."},
             timerName = "spring validator")
     public static class ValidatorAdvice {
         private static final TimerName timerName =
                 pluginServices.getTimerName(ValidatorAdvice.class);
         @IsEnabled
         public static boolean isEnabled() {
             return pluginServices.isEnabled();
         }
         @OnBefore
         public static TraceEntry onBefore(@BindReceiver Object validator) {
             return pluginServices.startTraceEntry(
                     MessageSupplier.from("spring validator: {}", validator.getClass().getName()),
                     timerName);
         }
         @OnAfter
         public static void onAfter(@BindTraveler TraceEntry traceEntry) {
             traceEntry.end();
         }
     }
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PluginServices.BooleanProperty
static interface	PluginServices.ConfigListener
static interface	PluginServices.DoubleProperty
static interface	PluginServices.StringProperty

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PluginServices()

Method Summary

Modifier and Type	Method and Description
abstract void	addTraceEntry(ErrorMessage errorMessage) Adds a trace entry with duration zero.
abstract void	addTransactionCustomAttribute(String name, String value) Adds an attribute on the current transaction with the specified name and value.
static PluginServices	get(String pluginId) Returns the PluginServices instance for the specified pluginId.
abstract PluginServices.BooleanProperty	getBooleanProperty(String name) Returns the boolean plugin property value with the specified name.
abstract PluginServices.DoubleProperty	getDoubleProperty(String name) Returns the Double plugin property value with the specified name.
abstract PluginServices.BooleanProperty	getEnabledProperty(String name)
abstract PluginServices.StringProperty	getStringProperty(String name) Returns the String plugin property value with the specified name.
abstract TimerName	getTimerName(Class<?> adviceClass) Returns the TimerName instance for the specified adviceClass.
abstract boolean	isEnabled() Returns whether the plugin is enabled.
abstract boolean	isInTransaction() Returns whether a transaction is already being captured.
abstract void	registerConfigListener(PluginServices.ConfigListener listener) Registers a listener that will receive a callback when the plugin's property values are changed, the plugin is enabled/disabled, or Glowroot is enabled/disabled.
abstract void	setTraceStoreThreshold(long threshold, TimeUnit unit) Overrides the default trace store threshold (Configuration > Traces > Default store threshold) for the current transaction.
abstract void	setTransactionError(ErrorMessage errorMessage) Marks the transaction as an error with the given message.
abstract void	setTransactionName(String transactionName) Set the transaction name that is used for aggregation.
abstract void	setTransactionType(String transactionType) Set the transaction type that is used for aggregation.
abstract void	setTransactionUser(String user) Sets the user attribute on the transaction.
abstract 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.
abstract QueryEntry	startQueryEntry(String queryType, String queryText, MessageSupplier messageSupplier, TimerName timerName) QueryEntry is a specialized type of TraceEntry that is aggregated by its query text.
abstract Timer	startTimer(TimerName timerName) Starts a timer for the specified timer name.
abstract TraceEntry	startTraceEntry(MessageSupplier messageSupplier, TimerName timerName) Creates and starts a trace entry with the given messageSupplier.
abstract TraceEntry	startTransaction(String transactionType, String transactionName, MessageSupplier messageSupplier, TimerName timerName) If there is no active transaction, a new transaction is started.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PluginServices

protected PluginServices()

Method Detail

get

public static PluginServices get(String pluginId)

Returns the PluginServices instance for the specified pluginId. 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).

registerConfigListener

public abstract void registerConfigListener(PluginServices.ConfigListener listener)

Registers a listener that will receive a callback when the plugin's property values are changed, the plugin is enabled/disabled, or Glowroot is enabled/disabled. This allows the useful plugin optimization of caching the results of isEnabled(), getStringProperty(String), getBooleanProperty(String), and getDoubleProperty(String) as volatile fields, and updating the cached values anytime PluginServices.ConfigListener.onChange() is called.

isEnabled

public abstract boolean isEnabled()

Returns whether the plugin is enabled. When Glowroot itself is disabled, this returns false. Plugins can be individually disabled on the configuration page.

getStringProperty

public abstract PluginServices.StringProperty getStringProperty(String name)

Returns the String plugin property value with the specified name. null is never returned. If there is no String plugin property with the specified name then the empty string "" is returned. Plugin properties are scoped per plugin. The are defined in the plugin's META-INF/glowroot.plugin.json file, and can be modified (assuming they are not marked as hidden) on the configuration page under the plugin's configuration section.

getBooleanProperty

public abstract PluginServices.BooleanProperty getBooleanProperty(String name)

Returns the boolean plugin property value with the specified name. If there is no boolean plugin property with the specified name then false is returned. Plugin properties are scoped per plugin. The are defined in the plugin's META-INF/glowroot.plugin.json file, and can be modified (assuming they are not marked as hidden) on the configuration page under the plugin's configuration section.

getDoubleProperty

public abstract PluginServices.DoubleProperty getDoubleProperty(String name)

Returns the Double plugin property value with the specified name. If there is no Double plugin property with the specified name then null is returned. Plugin properties are scoped per plugin. The are defined in the plugin's META-INF/glowroot.plugin.json file, and can be modified (assuming they are not marked as hidden) on the configuration page under the plugin's configuration section.

getEnabledProperty

public abstract PluginServices.BooleanProperty getEnabledProperty(String name)

getTimerName

public abstract 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

public abstract 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

public abstract 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 TraceEntry.endWithError(ErrorMessage) 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 duration exceeds the specified threshold, then the dummy entry will be escalated to a real entry. If TraceEntry.endWithError(ErrorMessage) 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

public abstract 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

public abstract 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

public abstract 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.

addTraceEntry

public abstract void addTraceEntry(ErrorMessage errorMessage)

Adds a trace entry with duration zero. It does not set the error attribute on the trace, which must be done with TraceEntry.endWithError(ErrorMessage) on the root entry. If the error message has no throwable, a stack trace is captured and attached to the trace 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, this method does nothing.

setTransactionType

public abstract 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

public abstract 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

public abstract void setTransactionError(ErrorMessage errorMessage)

Marks the transaction as an error with the given message. Normally transactions are only marked as an error if TraceEntry.endWithError(ErrorMessage) 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 TraceEntry.endWithError(ErrorMessage)), 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

public abstract 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.

addTransactionCustomAttribute

public abstract void addTransactionCustomAttribute(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.

setTraceStoreThreshold

public abstract void setTraceStoreThreshold(long threshold,
                                            TimeUnit unit)

Overrides the default trace store threshold (Configuration > Traces > Default store 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

public abstract 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.