Package com.linecorp.armeria.common.util

Interface Sampler<T>

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface
public interface Sampler<T>
Sampler is responsible for deciding if a particular trace should be "sampled", i.e. whether the overhead of tracing will occur and/or if a trace will be reported to the collection tier.

Zipkin v1 uses before-the-fact sampling. This means that the decision to keep or drop the trace is made before any work is measured, or annotations are added. As such, the input parameter to zipkin v1 samplers is the trace ID (lower 64-bits under the assumption all bits are random).

The instrumentation sampling decision happens once, at the root of the trace, and is propagated downstream. For this reason, the algorithm needn't be consistent based on trace ID.

  • Method Summary

    Modifier and Type Method Description
    static <T> Sampler<T> always()
    Returns a sampler that will always return true.
    boolean isSampled​(T object)
    Returns true if a request should be recorded.
    static <T> Sampler<T> never()
    Returns a sampler that will always return false.
    static <T> Sampler<T> of​(String specification)
    Returns a Sampler that is configured as specified in the given specification string.
    static <T> Sampler<T> random​(float probability)
    Returns a probabilistic sampler which samples at the specified probability between 0.0 and 1.0.
    static <T> Sampler<T> rateLimiting​(int samplesPerSecond)
    Returns a rate-limiting sampler which rate-limits up to the specified samplesPerSecond.

  • Method Details

    • random

      static <T> Sampler<T> random​(float probability)
      Returns a probabilistic sampler which samples at the specified probability between 0.0 and 1.0.
      Parameters:
      probability - the probability expressed as a floating point number between 0.0 and 1.0.

    • rateLimiting

      static <T> Sampler<T> rateLimiting​(int samplesPerSecond)
      Returns a rate-limiting sampler which rate-limits up to the specified samplesPerSecond.
      Parameters:
      samplesPerSecond - an integer between 0 and 2147483647

    • always

      static <T> Sampler<T> always()
      Returns a sampler that will always return true.

    • never

      static <T> Sampler<T> never()
      Returns a sampler that will always return false.

    • of

      static <T> Sampler<T> of​(String specification)
      Returns a Sampler that is configured as specified in the given specification string. The specification string must be formatted in one of the following formats:
      • "always"
        • Returns the Sampler that always samples.
      • "never"
        • Returns the Sampler that never samples.
      • "random=<probability>" where probability is a floating point number between 0.0 and 1.0
        • Returns a probabilistic Sampler which samples at the specified probability.
        • e.g. "random=0.05" to sample at 5% probability
      • "rate-limit=<samples_per_sec>" where samples_per_sec is a non-negative integer
        • Returns a rate-limiting Sampler which rate-limits up to the specified samples per second.
        • e.g. "rate-limit=10" to sample 10 samples per second at most

    • isSampled

      boolean isSampled​(T object)
      Returns true if a request should be recorded.
      Parameters:
      object - the object to be decided on, can be ignored