com.atlassian.plugin.instrumentation

Class PluginSystemInstrumentation

java.lang.Object

com.atlassian.plugin.instrumentation.PluginSystemInstrumentation

public class PluginSystemInstrumentation
extends Object

Optional instrumentation provider for plugin system internals.

The instrumentation may be safely invoked in any plugin system code, however will no-op unless this provider is enabled, which requires the following conditions to be met:

1. InstrumentRegistry is present in the class loader
2. The boolean system property com.atlassian.plugin.instrumentation.PluginSystemInstrumentation.enabled has been set

It is thus up to the application to provide the instrumentation classes and explicitly enable this instrumentation.

Note to maintainers: extreme care must be taken to ensure that instrumentation classes are not accessed at runtime if they are not present.

Since:

4.1

Field Summary

Fields

Modifier and Type	Field and Description
static String	INSTRUMENT_REGISTRY_CLASS
static File	REGISTRY_HOME_DIRECTORY
static String	REGISTRY_NAME

Method Summary

Modifier and Type	Method and Description
static String	getEnabledProperty() Name of the system property that enables instrumentation.
Optional<com.atlassian.instrumentation.InstrumentRegistry>	getInstrumentRegistry() Retrieve the instrument registry if instrumentation is enabled and present in the classloader.
static PluginSystemInstrumentation	instance() Singleton accessor
SingleTimer	pullSingleTimer(String name) Pull a timer from the instrument registry, if instrumentation is enabled and present in the classloader.
Timer	pullTimer(String name) Pull a timer from the instrument registry, if instrumentation is enabled and present in the classloader.

Methods inherited from class java.lang.Object

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

Field Detail

INSTRUMENT_REGISTRY_CLASS

public static final String INSTRUMENT_REGISTRY_CLASS

See Also:

Constant Field Values

REGISTRY_NAME

public static final String REGISTRY_NAME

See Also:

Constant Field Values

REGISTRY_HOME_DIRECTORY

public static final File REGISTRY_HOME_DIRECTORY

Method Detail

instance

@Nonnull
public static PluginSystemInstrumentation instance()

Singleton accessor

Returns:

one and only instance

getEnabledProperty

@Nonnull
public static String getEnabledProperty()

Name of the system property that enables instrumentation. Note that instrumentation defaults to "off".

Returns:

property name

getInstrumentRegistry

@Nonnull
public Optional<com.atlassian.instrumentation.InstrumentRegistry> getInstrumentRegistry()

Retrieve the instrument registry if instrumentation is enabled and present in the classloader.

Returns:

one and only registry

pullTimer

@Nonnull
public Timer pullTimer(@Nonnull
                                String name)

Pull a timer from the instrument registry, if instrumentation is enabled and present in the classloader.

This timer records wall-clock time and CPU time on the thread it was instantiated from.

This should be used for a section of code that we wish to repeatedly measure and aggregate results for.

The timer is Closeable and is expected to be used as per the following example:

 try (Timer ignored = PluginSystemInstrumentation.instance().pullTimer("getEnabledModuleDescriptorsByClass")) {
     // block we wish to repeatedly measure
 }
 

Parameters:

name - that the timer will report

Returns:

timer that may be empty - if no instrumentation it is still safe to close, which is a no-op

See Also:

pullSingleTimer(String)

pullSingleTimer

@Nonnull
public SingleTimer pullSingleTimer(@Nonnull
                                            String name)

Pull a timer from the instrument registry, if instrumentation is enabled and present in the classloader.

This timer records wall-clock time and CPU time on the thread it was instantiated from.

This should be used for a section of code that we wish to measure once - the date and time appended to its name.

The timer is Closeable and is expected to be used as per the following example:

 try (Timer ignored = PluginSystemInstrumentation.instance().pullSingleTimer("earlyStartup")) {
     // block we wish to measure once, with a unique name
 }
 

Parameters:

name - that the timer will report

Returns:

timer that may be empty - if no instrumentation it is still safe to close, which is a no-op

See Also:

pullTimer(String)