Nomes de métricas e cardinalidade de labels: unidades no nome, valores limitados nos labels

O que é

O nome de uma métrica diz o que é medido; os labels dizem para qual recorte. O guia de nomenclatura do Prometheus define as convenções: um prefixo de uma palavra para a aplicação ou o subsistema (http_, process_), uma unidade e uma grandeza por métrica, unidades base (segundos, bytes, não milissegundos nem megabytes), a unidade como sufixo no plural, _total para contagens acumulativas e _info para pseudométricas de metadados. Exemplos do guia: http_request_duration_seconds, process_cpu_seconds_total, http_requests_total. O guia também apresenta um teste: o sum() ou o avg() sobre todas as dimensões de label de uma métrica deve fazer sentido; se não fizer, os dados pertencem a duas métricas. Ele observa que outras convenções, entre elas a do OpenTelemetry, mantêm a unidade fora do nome, nos metadados; o Prometheus recomenda deixá-la no nome para que a configuração de alertas e dashboards continue legível sem precisar de um esquema.

Labels são as dimensões: operation="create", stage="extract", um código de status, um template de rota. O alerta do guia é a metade importante: cada combinação única de valores de label é uma nova série temporal, portanto os labels não devem carregar conjuntos ilimitados, como IDs de usuário ou endereços de e-mail.

Por que importa

Uma série consome memória, CPU, disco e rede durante todo o tempo em que existir. O guia de instrumentação dá ordens de grandeza: como diretriz, manter a cardinalidade de uma métrica abaixo de 10; tratar tudo o que passe de 100 ou que possa crescer como um caso para reduzir dimensões ou levar a análise para fora do sistema de monitoramento; e esperar que a grande maioria das métricas não tenha label algum. Um histograma clássico ingerido do modo clássico agrava o problema: cada bucket configurado cria uma série com o sufixo _bucket para cada combinação de labels, esteja o bucket preenchido ou não.

Como aplicar

• Nomeie por prefixo, grandeza, unidade e _total: queue_consumed_messages_total, job_last_success_timestamp_seconds.
• Use templates de rota, não caminhos brutos; classes ou códigos de status, não mensagens; apenas valores do tipo enumeração.
• Antes de adicionar um label, estime seus valores distintos e multiplique pelas combinações de labels já existentes e pelos buckets do histograma.
• Leve a análise por usuário ou por requisição para logs ou traces, onde alta cardinalidade é normal.
• Defina um limite de amostras por alvo quando o servidor oferecer essa opção (Prometheus: sample_limit na configuração de scrape) e crie alertas para o crescimento do número de séries, de modo que um label ruim seja detectado antes que o servidor sofra.

Armadilhas

Colocar o significado de um label no nome da métrica (http_requests_get_total) quebra a agregação. Misturar segundos e milissegundos sob um mesmo nome faz as séries colidirem sem aviso. Nomes de pod ou de contêiner em métricas de aplicação são limitados, mas mudam a cada deploy, criando um novo conjunto de séries toda vez. Os histogramas nativos mudam o modelo de custo dos buckets; o guia de histogramas citado explica as variantes.

O que um limite de amostras faz quando é atingido

sample_limit é a última linha de defesa, não um filtro: quando um alvo o excede, o Prometheus trata o scrape inteiro como falho, de modo que todas as métricas daquele serviço desaparecem de uma vez e os alertas que dependem delas ficam em silêncio. Use-o em três passos. Primeiro, descarte ou agregue os labels de risco conhecido em metric_relabel_configs, para que um label ruim custe uma métrica e não o alvo inteiro. Segundo, crie alertas para scrape_samples_post_metric_relabeling subindo em direção ao limite, por alvo, e para prometheus_tsdb_head_series no servidor, para que o crescimento seja percebido antes do corte. Terceiro, defina sample_limit bem acima da contagem normal, de modo que só um descontrole o ative. label_limit e os limites de comprimento de labels fazem o scrape falhar da mesma forma e merecem a mesma margem.