com.atlassian.util.profiling.strategy

Interface MetricStrategy

@Internal
 @ParametersAreNonnullByDefault
public interface MetricStrategy

Strategy for tracking metrics of profiled code blocks, to be used with Metrics.

Only metric timers and histograms created through Metrics.timer(String), Metrics.startTimer(String), Metrics.histogram(String), Timers.timerWithMetric(java.lang.String, java.lang.String) and Timers.startWithMetric(java.lang.String) will interact with configured MetricStrategy instances.

Since:

3.0

See Also:

Metrics, Timers

Method Summary

Modifier and Type	Method and Description
default void	cleanupMetrics(MetricsFilter filter) Removes existing metrics that are not accepted by the specified filter.
default void	incrementCounter(MetricKey metricKey, long deltaValue) Does not guarantee safety from lost-updates, check implementations.
default void	incrementGauge(MetricKey metricKey, long deltaValue) Does not guarantee safety from lost-updates, check implementations.
default void	onRequestEnd() Method that is called to signal that the request has completed.
default void	resetMetric(MetricKey metricKey) Resets (that may mean removal depending on the metric strategy) a specific metric that exactly matches a MetricKey.
default void	setConfiguration(MetricsConfiguration configuration) Method that is called when the strategy is registered.
default void	setGauge(MetricKey metricKey, long currentValue) Called to set the gauge by the value.
default Ticker	startLongRunningTimer(MetricKey metricKey) Called to time something that is long-running and could benefit from periodic updates on the timer duration.
default Ticker	startLongRunningTimer(String metricName) Called to time something that is long-running and could benefit from periodic updates on the timer duration.
default Ticker	startTimer(MetricKey metricKey) Called to mark the end of a block of code for which metrics should be calculated.
Ticker	startTimer(String metricName) Called to mark the end of a block of code for which metrics should be calculated.
default void	updateHistogram(MetricKey metricKey, long value) Called when a histogram is updated.
void	updateHistogram(String metricName, long value) Called when a histogram is updated.
default void	updateTimer(MetricKey metricKey, Duration time) Called when a metric is updated.
void	updateTimer(String metricName, long time, TimeUnit timeUnit) Called when a metric is updated.

Method Detail

cleanupMetrics

default void cleanupMetrics(MetricsFilter filter)

Removes existing metrics that are not accepted by the specified filter.

Note: this optional for strategies to support

Parameters:

filter - Metrics that are not accepted by the specified filter will be removed from this strategy.

Since:

4.1

resetMetric

default void resetMetric(MetricKey metricKey)

Resets (that may mean removal depending on the metric strategy) a specific metric that exactly matches a MetricKey.

Parameters:

metricKey - metric key to be reset.

Since:

4.9.0

onRequestEnd

default void onRequestEnd()

Method that is called to signal that the request has completed. Implementations of this method should clean up any request or thread scoped resources associated with profiling state, including closing any tickers that have not yet been closed.

setConfiguration

default void setConfiguration(MetricsConfiguration configuration)

Method that is called when the strategy is registered.

Parameters:

configuration - the configuration

startTimer

@Nonnull
Ticker startTimer(String metricName)

Called to mark the end of a block of code for which metrics should be calculated.

Parameters:

metricName - the name of metric

Returns:

a ticker that can be used to mark the end of the code block for which metrics should be calculated. Must be non-null, but can be Ticker.NO_OP if the strategy opts out of tracking.

startTimer

@Nonnull
default Ticker startTimer(MetricKey metricKey)

Called to mark the end of a block of code for which metrics should be calculated.

Parameters:

metricKey - the key of metric

Returns:

a ticker that can be used to mark the end of the code block for which metrics should be calculated. Must be non-null, but can be Ticker.NO_OP if the strategy opts out of tracking.

Since:

3.4

startLongRunningTimer

@Nonnull
default Ticker startLongRunningTimer(String metricName)

Called to time something that is long-running and could benefit from periodic updates on the timer duration.

Note: this optional for strategies to support This is an optional method, not all strategies will support this

Parameters:

metricName - the name of metric

Returns:

a ticker that can be used to mark the end of the code block for which metrics should be calculated. Must be non-null, but can be Ticker.NO_OP if the strategy opts out of tracking.

Since:

3.5.0

startLongRunningTimer

@Nonnull
default Ticker startLongRunningTimer(MetricKey metricKey)

Called to time something that is long-running and could benefit from periodic updates on the timer duration.

Note: this optional for strategies to support This is an optional method, not all strategies will support this

Parameters:

metricKey - the key of metric

Returns:

a ticker that can be used to mark the end of the code block for which metrics should be calculated. Must be non-null, but can be Ticker.NO_OP if the strategy opts out of tracking.

Since:

3.5.0

incrementCounter

default void incrementCounter(MetricKey metricKey,
                              long deltaValue)

Does not guarantee safety from lost-updates, check implementations.

Called to increment the count of the number of occurences.

Parameters:

metricKey - the key of counter

deltaValue - the amount to add to the counter

Since:

3.7.0

incrementGauge

default void incrementGauge(MetricKey metricKey,
                            long deltaValue)

Does not guarantee safety from lost-updates, check implementations.

Called to increment the gauge by the value. Starts from 0

Parameters:

metricKey - the key of the gauge

deltaValue - the change in gauge that should be recorded

Since:

4.8.0

updateHistogram

void updateHistogram(String metricName,
                     long value)

Called when a histogram is updated.

Parameters:

metricName - the histogram name

value - the value to record

updateHistogram

default void updateHistogram(MetricKey metricKey,
                             long value)

Called when a histogram is updated.

Parameters:

metricKey - the histogram key

value - the value to record

Since:

3.4

updateTimer

void updateTimer(String metricName,
                 long time,
                 TimeUnit timeUnit)

Called when a metric is updated.

Parameters:

metricName - the name of metric

time - the time to record

timeUnit - the time unit of time

updateTimer

default void updateTimer(MetricKey metricKey,
                         Duration time)

Called when a metric is updated.

Parameters:

metricKey - the key of timer

time - the time to record

Since:

3.4

setGauge

default void setGauge(MetricKey metricKey,
                      long currentValue)

Called to set the gauge by the value.

Parameters:

metricKey - the key of the gauge

currentValue - the value of gauge that should be recorded

Since:

4.8.0