> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atla-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sampling

> Control trace volume in high-throughput scenarios with smart sampling strategies

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.

<CodeGroup>
  ```python icon="python" lines theme={null}
  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  [!code ++]
  )
  ```

  ```code icon="square-js" theme={null}
  coming soon...
  ```
</CodeGroup>

## Sampling decision based on metadata:

If you want more flexibility, you can define a custom sampling decision function based on metadata.

<CodeGroup>
  ```python icon="python" lines theme={null}
  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),  # [!code ++]
  )
  ```

  ```code icon="square-js" theme={null}
  coming soon...
  ```
</CodeGroup>

<Info>
  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.
</Info>

## Custom Sampling

Implement your own sampling logic using [OpenTelemetry samplers](https://opentelemetry.io/docs/concepts/sampling/).

Here is an example:

```python icon="python" lines theme={null}
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()  # [!code ++]

configure(
    token=os.environ["ATLA_INSIGHTS_TOKEN"],
    sampling=my_sampler,  # [!code ++]
)
```

<Warning>
  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.
</Warning>