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

# Service Name Sampler

> This action is a [Service Action](../../../pipeline/actions/introduction#scope-categories) that samples traces based on the presence of specified services within a trace.

<Warning>
  This feature is in beta. It may be subject to changes and improvements based on user feedback.
</Warning>

## Considerations

<Warning>
  Before enabling the **Service Name Sampler**, please consider the following:

  * Only supports **traces**.
  * Sampling is trace-wide: either all spans in a trace are kept, or all are dropped.
  * The sampler introduces a delay of up to 30 seconds before traces are exported.
  * Traces with durations longer than 30 seconds might not be sampled correctly.
</Warning>

## Use Cases

**Targeted Trace Collection**

* Collect only traces involving specific microservices, such as `auth-service`, for debugging or focused observability.

**Cost Reduction**

* Significantly reduce collected trace volume by focusing on services that matter most.

## Configuration Options

The ServiceNameSampler action is configured using the `odigos.io/v1alpha1.Action` CRD with the `samplers` configuration section.

<AccordionGroup>
  <Accordion title="actionName">
    **actionName** `string`: A human-readable name for the action.

    * *Optional*
    * <Icon icon="triangle-exclamation" iconType="solid" color="yellow" /> Odigos does not use or assume any meaning from this field
  </Accordion>

  <Accordion title="notes">
    **notes** `string`: Free-form notes to describe the purpose or intent of this sampler.

    * *Optional*
    * <Icon icon="triangle-exclamation" iconType="solid" color="yellow" /> Odigos does not use or assume any meaning from this field
  </Accordion>

  <Accordion title="disabled">
    **disabled** `boolean`: Temporarily disables this sampler without deleting its configuration.

    * *Optional*, defaults to `false`
  </Accordion>

  <Accordion title="signals *">
    **signals** `string[]`: The signal types this action will operate on.

    * *Required*
    * Only `TRACES` is supported.
  </Accordion>

  <Accordion title="samplers *">
    **samplers** `object` : Configuration for sampling actions.

    * This field is *required* for this action type

    <AccordionGroup>
      <Accordion title="serviceNameSampler *">
        **serviceNameSampler** `object` : Configuration for the ServiceNameSampler.

        * This field is *required* for this action type

        <AccordionGroup>
          <Accordion title="services_name_filters *">
            **services\_name\_filters** `object[]` : An array of objects representing the filters for the services.

            * This field is *required*

            <AccordionGroup>
              <Accordion title="service_name *">
                **service\_name** `string` : Specifies the service name to search within the trace (Across all available spans).

                * This field is *required*
              </Accordion>

              <Accordion title="sampling_ratio *">
                **sampling\_ratio** `float` : Specifies the sample rate for all traces that contains `service_name`.

                * This field is *required*
              </Accordion>

              <Accordion title="fallback_sampling_ratio *">
                **fallback\_sampling\_ratio** `float` : Specifies the percentage of traces that don't meet the service name filter and that you still like to retain.

                * This field is *required*
              </Accordion>
            </AccordionGroup>
          </Accordion>
        </AccordionGroup>
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

<Info>
  A trace is sampled if it contains **at least one span** from a service listed in `services_name_filters` and passes the `sampling_ratio` check. Traces without any listed services may still be sampled based on the corresponding `fallback_sampling_ratio`.
</Info>

## Basic Example

This example samples **100%** of traces that contain `coupon-service` and **0%** of all other traces using the new Action CRD:

<Steps>
  <Step>
    Create a YAML file with the following content:

    ```yaml service-name-sampler.yaml theme={null}
    apiVersion: odigos.io/v1alpha1
    kind: Action
    metadata:
      name: coupon-service-sampler
      namespace: odigos-system
    spec:
      actionName: "coupon-sampler"
      signals:
        - TRACES
      samplers:
        serviceNameSampler:
          services_name_filters:
            - service_name: coupon-service
              sampling_ratio: 100
              fallback_sampling_ratio: 0
    ```
  </Step>

  <Step>
    Apply the sampler:

    ```bash theme={null}
    kubectl apply -f service-name-sampler.yaml
    ```
  </Step>
</Steps>

## Advanced Example

This example collects:

* 100% of traces with `payment-service`
* 50% of traces with `auth-service`
* 10% of traces that include **neither** of the above

```yaml advanced-service-name-sampler.yaml theme={null}
apiVersion: odigos.io/v1alpha1
kind: Action
metadata:
  name: multi-service-sampler
  namespace: odigos-system
spec:
  actionName: "multi-service-focus"
  signals:
    - TRACES
  samplers:
    serviceNameSampler:
      services_name_filters:
        - service_name: payment-service
          sampling_ratio: 100
          fallback_sampling_ratio: 10
        - service_name: auth-service
          sampling_ratio: 50
          fallback_sampling_ratio: 10
```

This setup ensures you always keep critical traces and still retain a sample of the rest for broader context.