pinpoint-apm/pinpoint · error · IllegalArgumentException

Invalid samplingRate

Error message

Invalid samplingRate 

What it means

PercentRateSampler samples a percentage of requests expressed in per-mille-style units bounded by MAX; the constructor rejects samplingRate <= 0 or >= MAX because 100% should use TrueSampler directly. Passing an out-of-range percentage throws IllegalArgumentException.

Solutions

1. Set the percent rate to a value strictly between 0 and MAX (e.g. 1..99 for percent semantics)
2. Use TrueSampler (or the sampler factory's 100% path) when full sampling is desired
3. Use a non-sampling sampler when zero sampling is desired instead of 0

Example fix

// before
sampler = new PercentRateSampler(100);
// after
sampler = Samplers.newSamplingRateSampler(SamplingType.PERCENT, 99); // or TrueSampler for 100%

long pct = Long.parseLong(props.getProperty("profiler.sampling.rate.sampling_rate"));
if (pct <= 0 || pct >= 100) throw new IllegalArgumentException("percent rate must be 1..99, got " + pct);

boolean isValidPercentRate(Long p) { return p != null && p > 0 && p < 100; }

try { sampler = new PercentRateSampler(pct); } catch (IllegalArgumentException e) { sampler = pct >= 100 ? new TrueSampler() : new FalseSampler(); }

When it happens

Trigger: Constructing new PercentRateSampler(0), a negative value, or a value >= MAX (e.g. 100 when MAX is 100), typically from Profiler.sampling.rate.sampling_rate config set to 0 or 100.

Common situations: User configures 100 intending "always sample" (must use TrueSampler / sampling type 100% semantics instead), or sets 0 intending "never" — both rejected by this constructor.

Related errors

• Invalid samplingRate
• Failed to detect pinpoint profile. Please add…
• access error
• Illegal report period:
• injectField error field

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/955209bb2d0078d2. Report an issue: GitHub.

Appendix: source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/sampler/PercentRateSampler.java:40

import java.util.concurrent.atomic.AtomicLong;

/**
 * @author emeroad
 * @author yjqg6666
 */
public class PercentRateSampler implements Sampler {
    // Supported range 100% ~ 0.01%
    public static final long MULTIPLIER = 100;
    public static final long MAX = 100 * MULTIPLIER;

    private final AtomicLong counter = new AtomicLong(0);

    private final long samplingRate;

    public PercentRateSampler(long samplingRate) {
        if (samplingRate <= 0 || samplingRate >= MAX) {
            // Use TrueSampler for 100%
            throw new IllegalArgumentException("Invalid samplingRate " + samplingRate);
        }
        this.samplingRate = samplingRate;
    }

    @Override
    public boolean isSampling() {
        final long seed = counter.addAndGet(samplingRate);
        final long remainder = MathUtils.floorMod(seed, MAX);
        if (remainder > 0 && remainder <= samplingRate) {
            return true;
        }
        return false;
    }

    @Override
    public String toString() {
        return "PercentRateSampler{" +
                "seedGen=" + counter +

View on GitHub (pinned to 744c3d3075)