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

# Trace Sampling Processor

> Sample OpenTelemetry traces at a given rate using the Trace ID, supporting both head-based and conditional tail-based sampling strategies.

## Description

Performs sampling of traces per a given rate using the Trace ID as the unique identifier. If a trace is rate selected, all spans of the trace are output.

<Note>
  This is an experimental feature that is still in development. For access to this feature, reach out to your Customer Support Manager or [support@mezmo.com](mailto:support@mezmo.com).
</Note>

## Use

Two well-known optimization techniques for traces are Deterministic Sampling (Head sampling) and more advanced Tail-based sampling. While head-based sampling will treat all traces equally and sample randomly, Tail-based sampling enables you to sample at different rates for traces you consider to have different levels of importance, based on attributes that traces contain, for example prioritizing traces with errors, latency, or traces that exceed certain performance thresholds. This is implemented in this Processor through conditional statements to define the trace.

<Note>
  This Processor supports sampling of [OTel traces only](https://opentelemetry.io/docs/concepts/signals/traces/).
</Note>

## Configuration

| Option                     | Description                                                                                           | Example                |
| -------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------- |
| Sample Type                | The type of sampling to invoke.                                                                       | `head`  `tail`         |
| Trace ID field             | The field to use as the identifier of a trace. Defaults to `.record.traceId`.                         | `.record.traceId`      |
| Rate                       | The rate at which to sample traces. For example, `10` means 1 out of every 10 traces will be sampled. | `10`                   |
| Parent Span ID (Tail Only) | The field to use as the parent span identifier. Defaults to `.record.parentSpanId`.                   | `.record.parentSpanId` |
| Conditional (Tail Only)    | Used in conjunction with Rate, a conditional statement to define the field for sampling               |                        |

<Note>
  By default, the Trace ID and Parent Span ID fields point to `.record.traceId` and `.record.parentSpanId`. These paths match the structure produced by the combined [OpenTelemetry Source](/telemetry-pipelines/open-telemetry-source), which nests `traceId` and `parentSpanId` under a `.record` property, so the Processor works with that Source without extra setup. If your traces store these values elsewhere, set each field to the path where the value lives.
</Note>

## Examples

Examples of OTEL traces that can be sampled using the Processor.

#### The head of a trace indicated by a null `parent_id` field

```json theme={null}
{
  "name": "hello",
  "context": {
    "traceid": "5b8aa5a2d2c872e8321cf37308d69df2",
    "spanid": "051581bf3cb55c13"
  },
  "parent_id": null,
  "start_time": "2022-04-29T18:52:58.114201Z",
  "end_time": "2022-04-29T18:52:58.114687Z",
  "attributes": {
    "http.route": "some_route1"
  },
  "events": [
    {
      "name": "Guten Tag!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

```

#### A related span under the same trace, indicated by the `parent_id` matching the `span_id` of the head

```json theme={null}
{
  "name": "hello-salutations",
  "context": {
    "traceid": "5b8aa5a2d2c872e8321cf37308d69df2",
    "spanid": "93564f51e1abe1c2"
  },
  "parent_id": "051581bf3cb55c13",
  "start_time": "2022-04-29T18:52:58.114492Z",
  "end_time": "2022-04-29T18:52:58.114631Z",
  "attributes": {
    "http.route": "some_route3"
  },
  "events": [
    {
      "name": "hey there!",
      "timestamp": "2022-04-29T18:52:58.114561Z",
      "attributes": {
        "event_attributes": 1
      }
    }
  ]
}

```