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

# Amostragem de traces

> Configure agregações ponderadas por amostra para dados de traces amostrados no ClickStack.

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

Serviços de alto throughput podem produzir milhões de spans por segundo. Armazenar cada span é caro, por isso as equipes costumam executar o [processador tail-sampling](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) do OpenTelemetry Collector para reter apenas 1 em cada N spans. Cada span retido carrega um atributo `SampleRate` que registra N.

Depois que os dados são amostrados, agregações simples produzem resultados incorretos: `count()` retorna N vezes menos eventos do que os que realmente ocorreram, `sum()` e `avg()` ficam enviesados, e os percentis se distorcem. Os dashboards mostram contagens de requisições, throughput e taxas de erro artificialmente baixas.

O ClickStack resolve isso com um engine de consulta sensível à amostragem. Quando você configura uma expressão de taxa de amostragem em uma fonte de traces, o construtor de consultas reescreve as agregações SQL para ponderar cada span pela sua taxa de amostragem — em dashboards, alertas e pesquisas ad hoc.

<div id="how-it-works">
  ## Como funciona
</div>

Quando uma fonte de traces tem `sampleRateExpression` configurada, o ClickStack a encapsula assim:

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

Spans sem o atributo `SampleRate` assumem peso 1 por padrão, portanto os dados não amostrados produzem resultados idênticos às consultas originais.

O construtor de consultas então reescreve as agregações:

| Agregação        | Antes              | Depois (corrigido para amostragem)        |
| ---------------- | ------------------ | ----------------------------------------- |
| count            | `count()`          | `sum(weight)`                             |
| count + condição | `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        | inalterado         | inalterado                                |
| count\_distinct  | inalterado         | inalterado                                |

<Note>
  Percentis com amostragem usam `quantileTDigestWeighted`, um sketch T-Digest aproximado. Os resultados ficam próximos, mas não exatos.
</Note>

<div id="configuring">
  ## Configurando a expressão da taxa de amostragem
</div>

Abra sua fonte de traces em **Configurações da fonte** e insira, no campo **Expressão da taxa de amostragem**, a expressão do ClickHouse que resulte na taxa de amostragem por `span`.

Por exemplo, se o processador tail-sampling do OpenTelemetry gravar a taxa em `SpanAttributes['SampleRate']`:

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/_TDydWLKO6Z3njo9/images/clickstack/trace-sampling-source-settings.png?fit=max&auto=format&n=_TDydWLKO6Z3njo9&q=85&s=638d1b58e8018ebc2551905ddcbe145f" alt="Campo Expressão da taxa de amostragem nas Configurações da fonte do ClickStack" size="lg" width="2300" height="690" data-path="images/clickstack/trace-sampling-source-settings.png" />

Depois de configurar, todos os gráficos, dashboards, alertas e painéis do dashboard de serviço aplicam automaticamente agregações ponderadas por amostragem. Não é necessário alterar consultas individuais.