Align TraceIdRatioBasedSampler with Java/Python implementations for cross-language compatibility

[Shrey93]

Is your feature request related to a problem? Please describe.

The current TraceIdRatioBasedSampler implementation in opentelemetry-js is incompatible with the Java and Python implementations, causing inconsistent sampling decisions across polyglot distributed systems. When trace context propagates between services via HTTP headers, all services receive the same trace ID but make different sampling decisions due to divergent hash algorithms. This breaks end-to-end trace visibility and creates gaps in distributed traces.

The JavaScript implementation XORs all 8-character chunks across the entire trace ID to produce a 32-bit hash, while both Java and Python implementations extract only the lower 64 bits of the trace ID. For the same trace ID and sampling ratio, JavaScript produces different sampling decisions than Java/Python, resulting in incomplete traces where some service spans are recorded while others are dropped.

This issue is particularly problematic when services need independent sampling control. Parent-based sampling would force downstream services to inherit upstream sampling decisions, preventing scenarios where Service A reduces sampling to zero during incidents while Service B maintains normal sampling rates for its own observability needs.

Describe the solution you'd like

Align NodeJS TraceIdRatioBasedSampler implementation with the Java and Python specifications by:

• Extracting the lower 64 bits of the trace ID (last 16 hex characters) using traceId.slice(16, 32)
• Converting to a signed 64-bit integer equivalent using BigInt
• Calculating the boundary as ratio × (2^63 - 1), with special cases for ratio 0.0 (use minimum safe integer) and ratio 1.0 (use maximum safe integer)
• Comparing the absolute value against the boundary using strict less-than

This ensures deterministic, cross-language compatible sampling decisions while preserving independent sampling control per service.

Describe alternatives you've considered

Alternative 1: Standardize all language implementations to use the JavaScript XOR approach. This would require coordinated changes across multiple SDKs (Java, Python, and others) and break existing deployments across the ecosystem.

Alternative 2: Use parent-based sampling exclusively. This forces downstream services to inherit upstream sampling decisions, eliminating the ability to adjust sampling rates independently per service. This approach fails when upstream services need to disable tracing during incidents while downstream services require continued observability.

Alternative 3: Implement custom sampling logic outside OpenTelemetry. This creates maintenance burden, loses community support, and fragments the observability ecosystem.

Additional context

The OpenTelemetry specification does not mandate a specific hash algorithm for TraceIdRatioBasedSampler, resulting in implementation divergence across language SDKs. Cross-language consistency is critical for polyglot microservice architectures where trace context propagates across service boundaries.

Both Java and Python implementations use the lower 64-bit extraction approach, making JavaScript the outlier. Aligning Node.js with this established pattern would improve interoperability for distributed systems using multiple language SDKs.

Reference implementations:

• Java: https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk/trace/src/main/java/io/opentelemetry/sdk/trace/samplers/TraceIdRatioBasedSampler.java
• Python: https://github.com/open-telemetry/opentelemetry-python/blob/main/opentelemetry-sdk/src/opentelemetry/sdk/trace/sampling.py (lines 256-276)
• JavaScript: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-sdk-trace-base/src/sampler/TraceIdRatioBasedSampler.ts

Why breaking backward compatibility is acceptable

This change will alter sampling decisions for existing JavaScript deployments, but the benefits outweigh the costs:

Cross-language consistency is a correctness issue, not a feature enhancement. The current implementation produces incorrect behavior in polyglot systems where trace context crosses service boundaries. Traces are silently fragmented, making distributed debugging difficult.

The impact is limited to sampling decisions, not trace functionality. Existing instrumentation code requires no changes. Only the statistical distribution of which traces are sampled will shift. No data loss occurs since unsampled traces were already being dropped.

Sampling ratios are probabilistic by design. Users already accept that exact trace counts vary based on traffic patterns and trace ID distribution. A one-time shift in which specific trace IDs are sampled is consistent with the probabilistic nature of sampling.

The alternative is permanent fragmentation. Without this change, JavaScript will remain incompatible with the broader OpenTelemetry ecosystem indefinitely, forcing users to choose between JavaScript and other languages for distributed tracing.

[Shrey93]

Would love to design and participate in implementation once this signed-off.

[pichlermarc]

Hmm, this actually just re-iterates what the specification mentions about this sampler:

WARNING: The exact algorithm was never specified. This sampler is not
defined so as to be compatible with any other SDK, therefore is considered unstable.
Only the configuration and creation APIs are stable.
It is recommended to use this sampler algorithm only for root spans
(in combination with ParentBased) because different language
SDKs or even different versions of the same language SDKs may produce inconsistent
results for the same input.

So it's not designed to be used in such a way. Users should always pair it with a parent based counterpart. It will then respect the sampling decision based on the sampled flag.

Q: @Shrey93 are you running into a situation where using it like this is not possible?

Maybe updating the documentation to reflect this could be a better approach, given that it's actually deprecated in the spec.

There is also this requirement that states that we SHALL NOT change it:

OpenTelemetry SDK implementors SHALL NOT remove or modify the behavior
of the original TraceIdRatioBased sampler until at least January 1, 2027.
At that time, SDK implementors are encouraged to silently
replace TraceIdRatioBased configuration with an equally-configured
ProbabilitySampler.

[Shrey93]

Thanks for the prompt reply @pichlermarc and for sharing these links.

Our use case aligns with the scenario described here:
open-telemetry/opentelemetry-specification#1413 (comment)

Requirements

US1: Independent Service Sampling with Consistent Trace Propagation

In a distributed micro-service architecture (Service A → Service B → Service C), each service needs independent span sampling control while maintaining trace context propagation. In the happy case, each service samples consistently at 5%. In the unhappy case, when Service A encounters a bug where span serialization becomes resource-intensive, sampling can be dialed down to 0% without affecting Service C's ability to emit spans.

US2: Downstream Service Sampling Autonomy

As a downstream service (Service C), sampling decisions should remain independent of frontier service (Service A) decisions. Service A might sample heavily (10%) for internal use cases, but this should not control Service C's sampling rate.

US3: Selective Intra-Service Span Sampling

Within a single micro-service, different spans require different sample rates based on payload characteristics. For example, compact spans sample at 5% while spans with heavy payloads sample at 1%.

• Why ParentBasedSampler Does Not Address These Requirements

For US1, when the frontier service (Service A) sets the ParentBasedSampler flag and dials down to 0%, both Service B and Service C stop emitting spans due to parent-based sampling inheritance.

For US2 and US3, the same constraint applies. Downstream services inherit sampling decisions from upstream parents, preventing independent sampling control based on service-specific requirements or span characteristics.

[Shrey93]

@pichlermarc , thoughts on the above? Are these use cases supported by Open Telemetry natively?

[pichlermarc]

@Shrey93 it's not implemented yet AFAIK but a ProbabilitySampler sounds like exactly what you need:

• https://github.com/open-telemetry/opentelemetry-specification/blob/3f7b3bee72d96f552405f5b049d910374e8a22a2/specification/trace/sdk.md?plain=1#L506-L561
• https://github.com/open-telemetry/opentelemetry-specification/blob/3f7b3bee72d96f552405f5b049d910374e8a22a2/specification/trace/tracestate-probability-sampling.md

[trentm]

it's not implemented yet AFAIK but a ProbabilitySampler sounds like exactly what you need:

Note that the Composable Probability Sampler is implemented, though it is using the old name with "TraceIDRationBased" in it: createComposableTraceIDRatioBasedSampler from @opentelemetry/sampler-composite: https://github.com/open-telemetry/opentelemetry-js/blob/main/experimental/packages/sampler-composite/README.md#samplers

(Aside: While that sampler-composite package was being written, this spec PR changed the name to ComposableProbability: https://github.com/open-telemetry/opentelemetry-specification/pull/4627/changes#diff-ace73543d690260e873d774428419c23895283b6c31177d405816b154d1f5aa0L48-R50

I think it might be worthwhile to change createComposableTraceIDRatioBasedSampler to use the newer name, especially while the sampler-composite package is still experimental.)

From the spec (https://opentelemetry.io/docs/specs/otel/trace/sdk/#built-in-composablesamplers):

Note that the top-level ProbabilitySampler can be implemented using a Composite(ComposableProbability(ratio)) configuration.

So you should be able to use:

import {
  createCompositeSampler,
  createComposableParentThresholdSampler,
  createComposableTraceIDRatioBasedSampler,
} from '@opentelemetry/sampler-composite';

const sampler1 = createCompositeSampler(
    createComposableParentThresholdSampler(
        createComposableTraceIDRatioBasedSampler(ratio)));
const sampler2 = createCompositeSampler(
        createComposableTraceIDRatioBasedSampler(ratio));

with or without the ParentThreshold handling.