Package org.forgerock.monitoring.api.instrument

Class DistributionSummary.Builder

java.lang.Object
org.forgerock.monitoring.api.instrument.DistributionSummary.Builder
Enclosing interface:
DistributionSummary
public static class DistributionSummary.Builder extends Object
Fluent builder for distribution summaries.

  • Method Details

    • tags

      public DistributionSummary.Builder tags(String... tags)
      Parameters:
      tags - Must be an even number of arguments representing key/value pairs of tags.

    • tags

      public DistributionSummary.Builder tags(Iterable<Tag> tags)
      Parameters:
      tags - Tags to add to the eventual distribution summary.
      Returns:
      The distribution summary builder with added tags.

    • tag

      public DistributionSummary.Builder tag(String key, String value)
      Parameters:
      key - The tag key.
      value - The tag value.
      Returns:
      The distribution summary builder with a single added tag.

    • description

      public DistributionSummary.Builder description(@Nullable String description)
      Parameters:
      description - Description text of the eventual distribution summary.
      Returns:
      The distribution summary builder with added description.

    • baseUnit

      public DistributionSummary.Builder baseUnit(@Nullable String unit)
      Parameters:
      unit - Base unit of the eventual distribution summary.
      Returns:
      The distribution summary builder with added base unit.

    • publishPercentiles

      public DistributionSummary.Builder publishPercentiles(@Nullable double... percentiles)
      Produces an additional time series for each requested percentile. This percentile is computed locally, and so can't be aggregated with percentiles computed across other dimensions (e.g. in a different instance). Use publishPercentileHistogram() to publish a histogram that can be used to generate aggregable percentile approximations.
      Parameters:
      percentiles - Percentiles to compute and publish. The 95th percentile should be expressed as 95.0

    • publishPercentileHistogram

      public DistributionSummary.Builder publishPercentileHistogram()
      Adds histogram buckets usable for generating aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g. Prometheus' histogram_quantile, Atlas' :percentiles).
      Returns:
      This builder.

    • publishPercentileHistogram

      public DistributionSummary.Builder publishPercentileHistogram(@Nullable Boolean enabled)
      Adds histogram buckets usable for generating aggregable percentile approximations in monitoring systems that have query facilities to do so (e.g. Prometheus' histogram_quantile, Atlas' :percentiles).
      Parameters:
      enabled - Value determining whether histgoram
      Returns:
      This builder.

    • sla

      public DistributionSummary.Builder sla(@Nullable long... sla)
      Publish at a minimum a histogram containing your defined SLA boundaries. When used in conjunction with publishPercentileHistogram(), the boundaries defined here are included alongside other buckets used to generate aggregable percentile approximations.
      Parameters:
      sla - Publish SLA boundaries in the set of histogram buckets shipped to the monitoring system.
      Returns:
      This builder.

    • minimumExpectedValue

      public DistributionSummary.Builder minimumExpectedValue(@Nullable Long min)
      Sets the minimum value that this distribution summary is expected to observe. Sets a lower bound on histogram buckets that are shipped to monitoring systems that support aggregable percentile approximations.
      Parameters:
      min - The minimum value that this distribution summary is expected to observe.
      Returns:
      This builder.

    • maximumExpectedValue

      public DistributionSummary.Builder maximumExpectedValue(@Nullable Long max)
      Sets the maximum value that this distribution summary is expected to observe. Sets an upper bound on histogram buckets that are shipped to monitoring systems that support aggregable percentile approximations.
      Parameters:
      max - The maximum value that this distribution summary is expected to observe.
      Returns:
      This builder.

    • histogramExpiry

      public DistributionSummary.Builder histogramExpiry(@Nullable Duration expiry)
      Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative histogram buckets). Samples are accumulated to such statistics in ring buffers which rotate after this expiry, with a buffer length of histogramBufferLength(Integer).
      Parameters:
      expiry - The amount of time samples are accumulated to a histogram before it is reset and rotated.
      Returns:
      This builder.

    • histogramBufferLength

      public DistributionSummary.Builder histogramBufferLength(@Nullable Integer bufferLength)
      Statistics emanating from a distribution summary like max, percentiles, and histogram counts decay over time to give greater weight to recent samples (exception: histogram counts are cumulative for those systems that expect cumulative histogram buckets). Samples are accumulated to such statistics in ring buffers which rotate after histogramExpiry(Duration), with this buffer length.
      Parameters:
      bufferLength - The number of histograms to keep in the ring buffer.
      Returns:
      This builder.

    • hierarchicalName

      public DistributionSummary.Builder hierarchicalName(String hierarchicalName)
      Parameters:
      hierarchicalName - the hierarchical representation of the meter name
      Returns:
      The builder with added hierarchical name.

    • register

      public DistributionSummary register(MeterRegistry registry)
      Add the distribution summary to a single registry, or return an existing distribution summary in that registry. The returned distribution summary will be unique for each registry, but each registry is guaranteed to only create one distribution summary for the same combination of name and tags.
      Parameters:
      registry - A registry to add the distribution summary to, if it doesn't already exist.
      Returns:
      A new or existing distribution summary.