feat(traceloop-sdk): add sampling_rate parameter to control trace volume

Add simplified sampling_rate parameter to Traceloop.init() for easy
trace sampling configuration without manually creating sampler objects.

Closes #2109

Author: Nikhil172913832

packages/traceloop-sdk/tests/test_sampling_rate.py

@@ -0,0 +1,91 @@
+import pytest
+from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from traceloop.sdk import Traceloop
+from traceloop.sdk.tracing.tracing import TracerWrapper
+class TestSamplingRate:
+    def test_init_with_sampling_rate(self):
+        if hasattr(TracerWrapper, "instance"):
+            _trace_wrapper_instance = TracerWrapper.instance
+            del TracerWrapper.instance
+        try:
+            exporter = InMemorySpanExporter()
+            client = Traceloop.init(
+                app_name="test-sampling-rate",
+                sampling_rate=0.5,
+                exporter=exporter,
+                disable_batch=True
+            )
+            assert client is None
+            assert hasattr(TracerWrapper, "instance")
+            assert TracerWrapper.instance is not None
+        finally:
+            if '_trace_wrapper_instance' in locals():
+                TracerWrapper.instance = _trace_wrapper_instance
+    def test_sampling_rate_validation(self):
+        if hasattr(TracerWrapper, "instance"):
+            _trace_wrapper_instance = TracerWrapper.instance
+            del TracerWrapper.instance
+        try:
+            exporter = InMemorySpanExporter()
+            with pytest.raises(ValueError, match="sampling_rate must be between 0.0 and 1.0"):
+                Traceloop.init(
+                    app_name="test-invalid-sampling-rate",
+                    sampling_rate=1.5,
+                    exporter=exporter,
+                    disable_batch=True
+                )
+            with pytest.raises(ValueError, match="sampling_rate must be between 0.0 and 1.0"):
+                Traceloop.init(
+                    app_name="test-invalid-sampling-rate",
+                    sampling_rate=-0.1,
+                    exporter=exporter,
+                    disable_batch=True
+                )
+        finally:
+            if '_trace_wrapper_instance' in locals():
+                TracerWrapper.instance = _trace_wrapper_instance
+    def test_sampling_rate_and_sampler_conflict(self):
+        if hasattr(TracerWrapper, "instance"):
+            _trace_wrapper_instance = TracerWrapper.instance
+            del TracerWrapper.instance
+        try:
+            exporter = InMemorySpanExporter()
+            sampler = TraceIdRatioBased(0.5)
+            with pytest.raises(ValueError, match="Cannot specify both 'sampler' and 'sampling_rate'"):
+                Traceloop.init(
+                    app_name="test-conflict",
+                    sampling_rate=0.5,
+                    sampler=sampler,
+                    exporter=exporter,
+                    disable_batch=True
+                )
+        finally:
+            if '_trace_wrapper_instance' in locals():
+                TracerWrapper.instance = _trace_wrapper_instance
+    def test_sampling_rate_edge_cases(self):
+        if hasattr(TracerWrapper, "instance"):
+            _trace_wrapper_instance = TracerWrapper.instance
+            del TracerWrapper.instance
+        try:
+            exporter = InMemorySpanExporter()
+            client = Traceloop.init(
+                app_name="test-sampling-zero",
+                sampling_rate=0.0,
+                exporter=exporter,
+                disable_batch=True
+            )
+            assert client is None
+            assert hasattr(TracerWrapper, "instance")
+            del TracerWrapper.instance
+            client = Traceloop.init(
+                app_name="test-sampling-one",
+                sampling_rate=1.0,
+                exporter=exporter,
+                disable_batch=True
+            )
+            assert client is None
+            assert hasattr(TracerWrapper, "instance")
+        finally:
+            if '_trace_wrapper_instance' in locals():
+                TracerWrapper.instance = _trace_wrapper_instance

packages/traceloop-sdk/traceloop/sdk/__init__.py

@@ -5,7 +5,7 @@
 from typing import Callable, List, Optional, Set, Union
 from colorama import Fore
 from opentelemetry.sdk.trace import SpanProcessor, ReadableSpan
-from opentelemetry.sdk.trace.sampling import Sampler
+from opentelemetry.sdk.trace.sampling import Sampler, TraceIdRatioBased
 from opentelemetry.sdk.trace.export import SpanExporter
 from opentelemetry.sdk.metrics.export import MetricExporter
 from opentelemetry.sdk._logs.export import LogExporter
@@ -62,6 +62,7 @@ def init(
         processor: Optional[Union[SpanProcessor, List[SpanProcessor]]] = None,
         propagator: TextMapPropagator = None,
         sampler: Optional[Sampler] = None,
+        sampling_rate: Optional[float] = None,
         traceloop_sync_enabled: bool = False,
         should_enrich_metrics: bool = True,
         resource_attributes: dict = {},
@@ -136,6 +137,19 @@ def init(
 
         print(Fore.RESET)
 
+        if sampling_rate is not None and sampler is not None:
+            raise ValueError(
+                "Cannot specify both 'sampler' and 'sampling_rate'. "
+                "Please use only one of these parameters."
+            )
+
+        if sampling_rate is not None:
+            if not 0.0 <= sampling_rate <= 1.0:
+                raise ValueError(
+                    f"sampling_rate must be between 0.0 and 1.0, got {sampling_rate}"
+                )
+            sampler = TraceIdRatioBased(sampling_rate)
+
         # Tracer init
         resource_attributes.update({SERVICE_NAME: app_name})
         TracerWrapper.set_static_params(