Package 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 Details

  • Method Details

    • 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

      @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: