Accepts a percentage of trace ids by comparing their absolute value against a potentially\n * dynamic boundary. eg {@code isSampled == abs(traceId) <= boundary}\n *\n *
While idempotent, this implementation's sample rate won't exactly match the input rate because\n * trace ids are not perfectly distributed across 64bits. For example, tests have shown an error\n * rate of 3% when 100K trace ids are {@link java.util.Random#nextLong random}.\n */\npublic abstract class CollectorSampler {\n public static final CollectorSampler ALWAYS_SAMPLE = CollectorSampler.create(1.0f);\n\n /**\n * Returns a trace ID sampler with the indicated rate.\n *\n * @param rate minimum sample rate is 0.0001, or 0.01% of traces\n */\n public static CollectorSampler create(float rate) {\n if (rate < 0 || rate > 1)\n throw new IllegalArgumentException(\"rate should be between 0 and 1: was \" + rate);\n final long boundary = (long) (Long.MAX_VALUE * rate); // safe cast as less <= 1\n return new CollectorSampler() {\n @Override\n protected long boundary() {\n return boundary;\n }\n };\n }\n\n protected abstract long boundary();\n\n /**\n * Returns true if spans with this trace ID should be recorded to storage.\n *\n *
Zipkin v1 allows storage-layer sampling, which can help prevent spikes in traffic from\n * overloading the system. Debug spans are always stored.\n *\n *
This uses only the lower 64 bits of the trace ID as instrumentation still send mixed trace","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-collector/core/src/main/java/zipkin2/collector/CollectorSampler.java#L16-L52","documentation":"CollectorSampler.create(float) validates the sample rate is within [0,1]; outside that range it throws IllegalArgumentException with the offending value in the message. The rate is converted to a boundary on Long.MAX_VALUE for trace-id-based sampling, so values like 1.5 or a percentage like 10 (meaning 10%) are rejected.","triggerScenarios":"Calling CollectorSampler.create(rate) with rate < 0 or > 1 — the classic case is passing a percentage (e.g. 10 for 10%, or 0.1 for 0.1%) instead of a fraction (0.1 for 10%).","commonSituations":"Env var COLLECTOR_SAMPLE_PERCENTAGE=10 piped straight into create(); confusion between basis points, percent, and probability; a default of -1 used as 'unset' sentinel reaching the sampler.","solutions":["Express the rate as a fraction in [0,1]: 10% sampling → 0.1f.","If your config is a percentage, divide by 100 before calling create.","Treat 'unset' sentinels (-1) by falling back to ALWAYS_SAMPLE or a documented default instead of forwarding them."],"exampleFix":"// before\nfloat rate = Float.parseFloat(env.get(\"COLLECTOR_SAMPLE_PERCENTAGE\")); // e.g. \"10\"\nCollectorSampler.create(rate); // throws 'rate should be between 0 and 1: was 10.0'\n\n// after\nfloat pct = Float.parseFloat(env.get(\"COLLECTOR_SAMPLE_PERCENTAGE\"));\nCollectorSampler.create(pct / 100.0f); // 10 -> 0.1","handlingStrategy":"validation","validationCode":"java\nfloat rate = Float.parseFloat(pct) / 100f;\nif (rate < 0f || rate > 1f) throw new IllegalArgumentException(\"sample rate must be 0-100%: \" + pct);\nreturn CollectorSampler.create(rate);","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Document config values as percentages but convert to fractions before create().","Never forward sentinel values like -1 to the sampler."],"tags":["zipkin","java","collector","sampling","configuration","validation"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}