> ## 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 based on metadata?

> How to use MetadataSampler to control trace logging based on metadata fields

SDK version `v0.0.24` includes the `MetadataSampler`, which allows you to easily decide whether or not to log a trace based on metadata fields.

## How it works

At configuration time, you can pass a `sampler` parameter to the `configure` function. The `MetadataSampler` accepts any function that maps metadata `Optional[dict[str, str]]` to a boolean.

## Basic Usage

```python theme={null}
from typing import Optional
from atla_insights import configure
from atla_insights.sampling import MetadataSampler

def sampling_fn(metadata: Optional[dict[str, str]]) -> bool:
    if metadata is None:
        return False
    return metadata.get("feature") == "feature_1"

configure(
    token="<YOUR_ATLA_INSIGHTS_TOKEN>", 
    sampler=MetadataSampler(sampling_fn)
)
```

## Complete Example

Check out our [full example on GitHub](https://github.com/atla-ai/atla-insights-sdk/blob/main/examples/metadata_sampling.py) that demonstrates metadata-based sampling in action.

## Use Cases

Metadata sampling is particularly useful for:

* **Environment-based filtering**: Different sampling rates for dev/staging/prod
* **Feature flagging**: Only trace when specific features are enabled
* **User-based sampling**: Focus on specific user segments or cohorts
* **Compliance**: Exclude traces containing sensitive user data based on metadata flags