By default, Atla Insights instruments and logs all traces. In high-throughput scenarios, you may want to sample traces rather than logging every execution to manage trace limits while maintaining observability.

​
Sampling ratio

If you want to sample a fixed ratio of traffic, we recommend using TraceRatioSampler. This is the simplest & most computationally efficient way to sample traces. 
import os
from atla_insights import configure
from atla_insights.sampling import TraceRatioSampler

configure(
    token=os.environ["ATLA_INSIGHTS_TOKEN"],
    sampler=TraceRatioSampler(rate=0.10),  # Logging 10% of traces
)

​
Sampling decision based on metadata:

If you want more flexibility, you can define a custom sampling decision function based on metadata. 
import os
import random
from typing import Optional

from atla_insights import configure
from atla_insights.sampling import MetadataSampler

def sampling_fn(metadata: Optional[dict[str, str]]) -> bool:
    """Custom sampling decision function.

    :param metadata (Optional[dict[str, str]]): The metadata to sample.
    :return (bool): Whether to sample the trace.
    """
    if metadata is None:
        return False

    if metadata.get("feature") == "feature_1":
        # Sample 50% of traffic for traces tagged as feature 1
        return bool(random.random() < 0.50)

    # Sample 10% of traffic otherwise
    return bool(random.random() < 0.10)


configure(
    token=os.environ["ATLA_INSIGHTS_TOKEN"],
    sampler=MetadataSampler(sampling_fn),  
)
Note that this is a more computationally intensive sampling method as we need to keep all spans in a trace alive in-memory until the entire trace ends.As metadata is mutable, we can only check the sampling decision function at the end of each trace.

​
Custom Sampling

Implement your own sampling logic using OpenTelemetry samplers. Here is an example: 
import os
from typing import Optional, Sequence

from atla_insights import configure
from opentelemetry.sdk.trace.sampling import Sampler, SamplingResult, Decision
from opentelemetry.trace import Link
from opentelemetry.util.types import Attributes

class MySampler(Sampler):
    ...

my_sampler = MySampler()  

configure(
    token=os.environ["ATLA_INSIGHTS_TOKEN"],
    sampling=my_sampler,  
)
Note that the Atla Insights platform is not intended to work well with partial traces.Therefore, we highly recommend using either ParentBased or StaticSampler samplers.This ensures either all traces are treated the same way or all spans in the same trace are treated the same way.