O OpenTelemetry Collector tem um processor chamado Cardinality Guardian, ainda marcado como alpha. Ele observa o crescimento dos labels e age quando um label começa a produzir valores que ninguém planejou. Eu queria saber quais das minhas métricas ele seguraria antes de colocar isso perto de um pipeline que me importa.

Então montei um laboratório pequeno com um Collector, um Prometheus onde eu consigo contar séries, um gerador de labels e um segundo Collector sem o processor, para todo número ter uma base de comparação.

No tag_only, o modo padrão, 200 identidades explodindo continuaram 200 séries. O processor marcou a explosão e todas as séries chegaram no backend do mesmo jeito. Dos oito formatos de métrica do OTLP que enviei, dois são reduzidos, Delta Sum e Gauge. Histogramas, histogramas exponenciais, summaries e cumulative sums saem do processor com a cardinalidade inteira nos três modos. O upstream documenta isso. Eu passei batido na primeira vez.

200 -> 200tag_only, padrãoDetecta a explosão e encaminha todas as séries.
200 -> 24Delta Sum, GaugeOs únicos dois formatos reagregados pelos modos que aplicam a regra.
200 -> 200Seis formatos sem reagregaçãoCardinalidade inteira nos três modos.

A montagem #

Tudo roda local em Docker. O Collector está fixado na 0.162.0 e verificado contra o checksum do release, o Prometheus na 3.15.0 pelo digest da imagem. As métricas entram por OTLP gRPC com temporalidade delta, e eu conto o que sai do exporter do Prometheus.

processors:
  cardinality_guardian:
    max_cardinality_delta_per_epoch: 20
    epoch_duration_seconds: 10
    enforcement_mode: tag_only
    never_drop_labels:
      - region
      - environment
      - service.name
    top_offenders_count: 20
    max_tracker_count: 10000

Vinte valores novos a cada dez segundos é o menor ajuste que dispara o processor sem tráfego de produção. Não leve esse valor para um pipeline de verdade.

Nove execuções de corretude verificam as contagens exatas de séries, labels e marcadores, e 84 execuções de benchmark comparam com o Collector sem processor nenhum. Cada cenário roda três vezes porque a estimativa de cardinalidade por baixo é probabilística.

O tag_only só detecta #

Cada cenário envia 200 data points. Os que explodem carregam um user.id único ou uma rota de pedido única por ponto. O controle carrega quatro rotas fixas.

ModoRota estávelContador por user.idContador por rota sem tratamentoHistograma
tag_only4200200200
overflow_attribute42121200
strip_and_reaggregate42121200

No tag_only, 180 das 200 séries carregam otel.metric.overflow=true e todas as 200 continuam com o label original sem limite. O README do upstream diz que o tag_only não protege o backend sozinho e precisa de um routing connector depois dele para mandar as métricas marcadas para algum lugar barato. Então o modo mais seguro de ligar também é o que não muda nada no que você armazena.

Vinte valores chegam antes do limite de crescimento ser cruzado e mantêm a identidade própria. Tudo depois colapsa em um. Daí o 21.

Só dois formatos colapsam #

Mesma carga, 200 valores únicos, todos os formatos do OTLP enviados juntos. Os seis da última linha são Cumulative Sum, histograma delta e cumulativo, histograma exponencial delta e cumulativo, e Summary.

Formato da métricabaselinetag_onlyoverflow_attributestrip_and_reaggregate
Delta Sum2002002424
Gauge2002002424
Os outros seis formatos200200200200

Juntar data points que passaram a dividir a mesma identidade só é seguro num Delta Sum, onde você soma os valores, e num Gauge, onde vence o timestamp mais novo. Fluxos cumulativos exigem um estado que o processor não guarda, buckets de histograma exigem fronteiras alinhadas, e quantis não dá para juntar de jeito nenhum. Esses tipos caem de volta para a marcação em vez de produzir um número errado, e eu prefiro assim. O 24 são vinte sobreviventes mais uma identidade colapsada por valor do label limitado http.method, que tem quatro.

Um histograma clássico com 200 identidades são 2.200 séries no Prometheus deste laboratório quando se conta buckets, sum e count, e um summary são 1.000. Nenhum dos dois se mexe em nenhum modo. Se as suas métricas caras são histogramas de latência, que na minha experiência costumam ser, esse processor ainda não encosta nelas.

O epoch só enxerga crescimento #

Li max_cardinality_delta_per_epoch e presumi que cada epoch entrega uma margem nova de vinte valores, então um fluxo contínuo de valores novos ficaria cortado em uns vinte por epoch para sempre. Para conferir, enviei 200 valores novos por epoch ao longo de três epochs, 600 no total, e comparei com 2.000 valores únicos dentro de um epoch só.

Cargabaselinetag_onlyoverflow_attributestrip_and_reaggregate
2.000 únicos dentro de um epoch200020002424
200 novos por epoch em três epochs600600424424

A rajada para em 24. A carga contínua mantém 424 das suas 600 identidades. O primeiro epoch é cortado em 24 e o segundo e o terceiro passam inteiros, 24 mais 200 mais 200.

O processor age quando a estimativa do epoch atual passa a do anterior por mais que o limite, (currCount - prevCount) > p.getLimit(metricName). Minha carga trocava 200 identidades por 200 que ele nunca tinha visto a cada epoch, então a estimativa ficou perto de 200 e a diferença perto de zero. As notas de design do upstream dizem que isso é proposital. Um label com cinquenta mil valores estáveis não é problema, e o crescimento desde o último epoch é o sinal. O meu modelo teria me feito esperar proteção contra um gotejamento constante que o processor foi desenhado para ignorar.

O que eu faria com isso #

Primeiro eu listaria quais das minhas métricas caras são Delta Sum ou Gauge. Se forem principalmente histogramas de latência, ainda não é o controle de que preciso. Se eu fosse ligar, o tag_only entraria com um routing connector desde o começo, o never_drop_labels estaria definido antes do primeiro rollout, e o epoch_duration_seconds ficaria maior que uma rajada normal de deploy para tráfego comum não parecer crescimento. O contador de economia estimada multiplica um valor em dólar que eu configurei por uma contagem, então o número que ele devolve saiu da minha própria configuração.

O caso que eu mais encontro é um label explodindo por trimestre, do mesmo time. O gate segura cada um como uma rajada, e nada nele sabe que o label que acabou de colapsar é o terceiro daquele serviço.

O que este laboratório não te conta #

Ele roda numa máquina só com Docker Compose, então nada disso é modelo de capacidade, e as amostras de CPU e memória não dá para atribuir ao processor porque o gerador divide o mesmo host. O upstream tem microbenchmarks em Go para isso.

A estimativa usa HyperLogLog++ com cerca de 0,81% de erro padrão, então as contagens perto do limite se mexem um pouco entre execuções. Todo número aqui é a mediana de três repetições, com a faixa guardada nos resultados crus.

O exporter do Prometheus no Collector converte histogramas exponenciais para o formato nativo e este laboratório os lê como texto, então só chega o bucket +Inf e nada disso cobre histogramas nativos. O post seguinte liga o scrape nativo e mede. Cada execução sobe o stack do zero, então nada aqui cobre deriva ao longo de horas ou reinícios, e eu medi um limite e uma duração de epoch.

Três contadores do Collector que eu queria não apareceram no nível de telemetria que usei. Os resultados registram isso como null, porque um zero afirmaria que o processor não deixou nada passar.

Rode você mesmo #

git clone https://github.com/cauebraz/opentelemetry-cardinality-lab
cd opentelemetry-cardinality-lab
just setup
just check
just experiment
just benchmark

O just experiment produz a primeira tabela e o just benchmark produz as outras. Está tudo no opentelemetry-cardinality-lab, incluindo o JSON cru por trás de cada tabela aí em cima e as asserções que derrubam a execução quando o comportamento do upstream muda. O processor em si está documentado no repositório contrib.

Se você rodar contra uma carga com formato diferente da minha e os números não baterem, abra uma issue no repositório do laboratório com o que você mandou e o que saiu, que eu confiro se as minhas asserções estão erradas.