com.netflix.spectator.api.patterns

Class CardinalityLimiters

java.lang.Object

com.netflix.spectator.api.patterns.CardinalityLimiters

public final class CardinalityLimiters
extends Object

Helper functions to help manage the cardinality of tag values. This should be used anywhere you cannot guarantee that the tag values being used are strictly bounded. There is support for two different modes, 1) selecting the first N values that are seen, or 2) selecting the most frequent N values that are seen.

Sample usage:

 class WebServer {

   // Limiter instance, should be shared for all uses of that
   // tag value
   private final Function<String, String> pathLimiter =
     CardinalityLimiters.mostFrequent(10);

   private final Registry registry;
   private final Id baseId;

   public WebServer(Registry registry) {
     this.registry = registry;
     this.baseId = registry.createId("server.requestCount");
   }

   public Response handleRequest(Request req) {
     Response res = doSomething(req);

     // Update metrics, use limiter to restrict the set of values
     // for the path and avoid an explosion
     String pathValue = pathLimiter.apply(req.getPath());
     Id id = baseId
       .withTag("path", pathValue)
       .withTag("status", res.getStatus());
     registry.counter(id).increment();
   }
 }
 

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTO_ROLLUP Replacement value that is used if the values are rolled up.
static String	OTHERS Replacement value that is used if the number of values exceeds the limit.

Method Summary

Modifier and Type	Method and Description
static Function<String,String>	first(int n) Restrict the cardinality of the input to the first n values that are seen.
static Function<String,String>	mostFrequent(int n) Restrict the cardinality of the input to the top n values based on the frequency of the lookup.
static Function<String,String>	rollup(int n) Rollup the values if the cardinality exceeds n.

Methods inherited from class java.lang.Object

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

Field Detail

OTHERS

public static final String OTHERS

Replacement value that is used if the number of values exceeds the limit.

See Also:

Constant Field Values

AUTO_ROLLUP

public static final String AUTO_ROLLUP

Replacement value that is used if the values are rolled up.

See Also:

Constant Field Values

Method Detail

first

public static Function<String,String> first(int n)

Restrict the cardinality of the input to the first n values that are seen.

Parameters:

n - Number of values to select.

Returns:

The input value if it is within the bounds or is selected. Otherwise map to OTHERS.

mostFrequent

public static Function<String,String> mostFrequent(int n)

Restrict the cardinality of the input to the top n values based on the frequency of the lookup. This limiter is useful when the frequency of the values is non-uniform and the most common are the most important. If there are many values with roughly the same frequency, then it will use a first(int) limiter to keep the number of values within bounds.

The limiter will adjust to changes in the frequency over time, but it must also protect against high rates of churn in the values. Keep in mind that this can cause a delay in new high frequency value being used instead of being grouped as part of OTHERS.

Parameters:

n - Number of values to select.

Returns:

The input value if it is within the bounds or is selected. Otherwise map to OTHERS.

rollup

public static Function<String,String> rollup(int n)

Rollup the values if the cardinality exceeds n. This limiter will leave the values alone as long as the cardinality stays within the limit. After that all values will get mapped to AUTO_ROLLUP.

Parameters:

n - Maximum number of distinct values allowed for the lifetime of the limiter.

Returns:

The input value if it is within the bounds or is selected. Otherwise map to AUTO_ROLLUP.