Package com.atlassian.diagnostics.ipd.api.registry

Interface IpdRegistry

All Known Implementing Classes:
AbstractIpdMeterRegistry, NoopIpdRegistry
public interface IpdRegistry
Interface for managing and registering various types of meters in the IPD (In-Product Diagnostics) registry. All meters are registered with a unique key, which consists of a name and a set of tags. By default, meters are visible through JMX and log files.

Provides methods to register, retrieve, and manage meters such as counters, custom meters, value meters, and stats meters.

Since:
3.0.0

  • Method Details

    • register

      <T extends IpdMeter> T register(MeterFactory<T> factory, String name, MeterTag... tags)
      returns an `IpdMeter` of type 'T' with the given name and tags. If a meter with the given name and tags does not exist, a new one will be created using the provided factory.
      Type Parameters:
      T - the type of the meter
      Parameters:
      factory - the factory to use to create the meter instance
      name - the name of the meter
      tags - the tags of the meter
      Returns:
      existing or the newly registered `IpdMeter`

    • get

      @Nullable IpdMeter get(MeterKey meterKey)
      Retrieves an `IpdMeter` by its `MeterKey`.
      Parameters:
      meterKey - the key of the meter to retrieve
      Returns:
      the `IpdMeter` associated with the given key, or `null` if no such meter exists

    • getMeters

      Collection<IpdMeter> getMeters()
      Retrieves all registered `IpdMeter` instances as an immutable set.
      Returns:
      an immutable set of all registered `IpdMeter` instances

    • getMeters

      Collection<IpdMeter> getMeters(String prefix)
      Retrieves all registered `IpdMeter` instances with the given prefix as an immutable set.
      Parameters:
      prefix - the prefix to filter by
      Returns:
      an immutable set of all registered `IpdMeter` instances with the given prefix

    • getMeterKeys

      Set<MeterKey> getMeterKeys()
      Retrieves all keys of registered `IpdMeter` instances as an immutable set.
      Returns:
      an immutable set of all registered meter keys

    • getMeterKeys

      Set<MeterKey> getMeterKeys(String prefix)
      Retrieves all keys of registered `IpdMeter` instances with the given prefix as an immutable set.
      Parameters:
      prefix - the prefix to filter by
      Returns:
      an immutable set of all registered meter keys with the given prefix

    • unregisterAllDisabledMetrics

      void unregisterAllDisabledMetrics()
      Unregisters all disabled metrics.

      This method iterates through all registered `IpdMeter` instances and unregisters from JMX those that are disabled. Meters are considered disabled if their `IpdMeter#isEnabled` method returns `false`.

    • remove

      void remove(MeterKey meterKey)
      Removes the `IpdMeter` associated with the given `MeterKey`. Does nothing if no such meter exists.

      The existing instance of IpdMeter will be closed. See IpdMeter.close().

      Parameters:
      meterKey - the key of the meter to remove

    • removeAll

      void removeAll()
      Removes all registered `IpdMeter` instances.

    • removeAll

      void removeAll(String prefix, MeterTag... tags)
      Removed all registered `IpdMeter` instances with the given prefix and tags.

      If any of the tags are not present in the meter, it will not be removed, but any additional tags in the meter will not prevent it from being removed.

      Parameters:
      prefix - the prefix to filter by
      tags - the tags to filter by

    • removeAllWithAnyTag

      void removeAllWithAnyTag(String prefix, Set<MeterTag> tags)
      Removes all registered `IpdMeter` instances that match prefix and any of the given tags.

      If none of the tags are present in the meter, it will not be removed.

      Useful for removing a few meters with different tags, but the same prefix. For example, removing user directory metrics: 

               removeAllWithAnyTag("user.directory",
              Set.of(
                  MeterTag.of("name", "ldap"),
                  MeterTag.of("name", "crowd")));
      This will remove all meters with prefix "user.directory" and tags "name=ldap" or "name=crowd", but not "name=my_directory".
      Parameters:
      prefix - the prefix to filter by
      tags - the tags to filter by

    • removeIf

      void removeIf(Predicate<IpdMeter> predicate)
      Removes all registered `IpdMeter` instances that match the given predicate.
      Parameters:
      predicate - the predicate to filter by

    • removeIf

      void removeIf(String prefix, Predicate<IpdMeter> predicate)
      Removes all registered `IpdMeter` instances with the given prefix that also match the given predicate.
      Parameters:
      prefix - the prefix to filter by
      predicate - the predicate to filter by

    • retainIf

      void retainIf(String prefix, Predicate<IpdMeter> predicate)
      Iterates through all registered metrics matching prefix and removes those that do not match the predicate. For example, removing user directory metrics: 
           retainIf("user.directory",
         meter -> "ldap".equals(meter.getKey().getTag("name")));
      After this call, meters that match "user.directory" but don't have tag "name=ldap" will be removed.
      Parameters:
      prefix - the prefix to filter by
      predicate - the predicate to filter by

    • valueAndStats

      default ValueAndStatsMeterWrapper valueAndStats(String name, MeterTag... tags)
      Returns metric wrapper containing both value and statistic metrics.
      Parameters:
      name - meter name
      tags - meter tags
      Returns:
      Wrapper containing existing or new meters

    • value

      ValueMeter value(String name, MeterTag... tags)
      Returns value meter for a given name and tags.
      Parameters:
      name - meter name
      tags - meter tags
      Returns:
      Existing or new meter

    • setValue

      default void setValue(String name, long value, MeterTag... tags)
      Sets value to the existing or new value meter. Equivalent to 
      ipdRegistry.value(name, tags).update(value)
      Parameters:
      name - meter name
      value - value to set
      tags - meter tags

    • stats

      StatsMeter stats(String name, MeterTag... tags)
      Returns stats meter for a given name and tags.
      Parameters:
      name - meter name
      tags - meter tags
      Returns:
      Existing or new meter

    • addStats

      default void addStats(String name, long value, MeterTag... tags)
      Updates stats meter with a given value. Equivalent to 
      ipdRegistry.stats(name, tags).update(value)
      Parameters:
      name - meter name
      value - value to set
      tags - meter tags

    • addStats

      default void addStats(String name, long value, TimeUnit timeUnit, MeterTag... tags)
      Updates stats meter with a given value. Equivalent to 
      ipdRegistry.stats(name, tags).update(value, timeUnit)
      Parameters:
      name - meter name
      value - value to set
      timeUnit - time unit of the value
      tags - meter tags

    • counter

      CounterMeter counter(String name, MeterTag... tags)
      Returns counter meter for a given name and tags.
      Parameters:
      name - meter name
      tags - meter tags
      Returns:
      Existing or new meter

    • incrementCounter

      default void incrementCounter(String name, MeterTag... tags)
      Increments counter meter by 1. Equivalent to 
      ipdRegistry.counter(name, tags).increment(1)
      Parameters:
      name - meter name
      tags - meter tags

    • custom

      <T> CustomMeter<T> custom(String name, Class<T> type, MeterTag... tags)
      Returns custom meter for a given name, tags and type.

      'type' parameter points to class which implements interface annotated with @MXBean. Getters in this interface will define meter attributes.
      This class has to have no argument constructor.

      See 'type' example implementation IpdConnectionState
      Type Parameters:
      T - Type defining meter attributes
      Parameters:
      name - metric name
      type - points to custom meter MBean implementation. This class has to implement interface annotated with @MXBean. Getters in this interface will define meter attributes.
      tags - meter tags
      Returns:
      existing or new meter

    • custom

      <T> CustomMeter<T> custom(String name, CustomMeter.MBeanSupplier<T> instance, MeterTag... tags)
      Returns custom meter for a given name, tags and instance.

      'instance' object has to be of class which implements interface annotated with @MXBean. Getters in this interface will define meter attributes.

      See 'type' example implementation IpdConnectionState

      Important note:
      Returned meter will reference given instance object only on creation. If CustomMeter for a give name and tags is already registered, it will be returned with the existing instance object and provided 'instance' parameter will be ignored.

      Type Parameters:
      T - Type defining meter attributes
      Parameters:
      name - metric name
      instance - this objects class has to implement interface annotated with @MXBean. Getters in this interface will define meter attributes.
      tags - meter tags
      Returns:
      existing or new meter

    • statsCopy

      JmxCopyMeter statsCopy(String name, ObjectName objectToCopy, MeterTag... tags)
      Returns an IPD meter which copies stats attributes of existing JMX meter. All attribute changes in the original metric will be reflected in JMX and log file after calling JmxCopyMeter.update().
      Parameters:
      name - meter name with postfix
      objectToCopy - object name of the JMX bean to copy attributes from
      tags - meter tags
      Returns:
      existing or new meter

    • shutdown

      void shutdown()
      Shuts down the registry and unregisters all meters.