> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Сэмплирование трасс

> Настройте взвешенные с учётом выборки агрегации для сэмплированных данных трасс в ClickStack.

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

Сервисы с высокой пропускной способностью могут генерировать миллионы спанов в секунду. Хранить каждый спан дорого, поэтому команды обычно используют [процессор tail-sampling](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) в OpenTelemetry Collector, чтобы сохранять только один из N спанов. Каждый сохранённый спан содержит атрибут `SampleRate`, в котором записано значение N.

После сэмплирования данных наивные агрегации дают неверный результат: `count()` возвращает в N раз меньше событий, чем произошло на самом деле, `sum()` и `avg()` оказываются смещёнными, а процентильные значения сдвигаются. Панели мониторинга показывают заниженные значения числа запросов, пропускной способности и частоты ошибок, что вводит в заблуждение.

ClickStack решает эту проблему с помощью движка запросов, учитывающего сэмплирование. Когда вы настраиваете выражение коэффициента выборки для источника трассировки, конструктор запросов переписывает SQL-агрегации так, чтобы вес каждого спана учитывался по его коэффициенту выборки — в панелях мониторинга, оповещениях и ad-hoc поисковых запросах.

<div id="how-it-works">
  ## Как это работает
</div>

Когда для источника трассировки задан `sampleRateExpression`, ClickStack оборачивает его в следующую конструкцию:

```sql theme={null}
greatest(toUInt64OrZero(toString(expr)), 1)
```

Для спанов без атрибута `SampleRate` по умолчанию назначается вес 1, поэтому данные без сэмплирования дают те же результаты, что и исходные запросы.

Затем конструктор запросов переписывает агрегации:

| Aggregation | Before | After (sample-corrected) |
| - | - | - |
| count | `count()` | `sum(weight)` |
| count + condition | `countIf(cond)` | `sumIf(weight, cond)` |
| avg | `avg(col)` | `sum(col * weight) / sum(weight)` |
| sum | `sum(col)` | `sum(col * weight)` |
| quantile(p) | `quantile(p)(col)` | `quantileTDigestWeighted(p)(col, weight)` |
| min / max | unchanged | unchanged |
| count\_distinct | unchanged | unchanged |

<Note>
  Для перцентилей при сэмплировании используется `quantileTDigestWeighted` — приблизительный эскиз T-Digest. Результаты близки к точным, но не совпадают с ними полностью.
</Note>

<div id="configuring">
  ## Настройка выражения коэффициента выборки
</div>

Откройте источник трассировки в **Source Settings** и в поле **Sample Rate Expression** введите выражение ClickHouse, которое вычисляет коэффициент выборки для каждого спана.

Например, если ваш процессор tail-sampling OpenTelemetry записывает это значение в `SpanAttributes['SampleRate']`:

<Image img="https://mintcdn.com/private-7c7dfe99-parallel-read-in-order-multi-part/RIApJQXHeIIpcfQr/images/clickstack/trace-sampling-source-settings.webp?fit=max&auto=format&n=RIApJQXHeIIpcfQr&q=85&s=d50783fa6255b2f18fa25ff60b914e04" alt="Поле Sample Rate Expression в настройках источника ClickStack" size="lg" width="2300" height="690" data-path="images/clickstack/trace-sampling-source-settings.webp" />

После настройки все графики, панели мониторинга, оповещения и панели мониторинга сервисов автоматически применяют агрегации с учетом коэффициента выборки. Изменять отдельные запросы не нужно.