Para criar métricas customizadas em uma mini app PHP, escolha o instrumento conforme o dado: counter para totais acumulados, gauge para valores que sobem e descem e histogram para observar distribuições, como durações. Em PHP, você pode instrumentar diretamente com um cliente Prometheus ou usar a API e o SDK do OpenTelemetry; a decisão depende do ecossistema de coleta e de como os dados precisam sobreviver entre execuções.
Escolha entre um cliente Prometheus e OpenTelemetry
As duas opções permitem instrumentar métricas em PHP, mas não há uma comparação oficial que determine uma escolha universal. Considere qual padrão de telemetria o projeto já usa, onde os dados serão coletados e se precisam persistir entre requisições ou processos.
As an Amazon Associate I earn from qualifying purchases.
| Opção | Como funciona | O que considerar |
|---|---|---|
| PromPHP/prometheus_client_php | Registra e atualiza counters, gauges e histograms diretamente; o projeto inclui adaptadores de armazenamento. | A documentação diz que o adaptador em memória pode servir para um cron job ou script de longa duração quando não é preciso persistir métricas entre requisições. Isso não o torna automaticamente adequado a uma aplicação web em que cada requisição inicia um processo novo. |
| OpenTelemetry PHP | A API instrumenta o código e o SDK inicializa a telemetria da aplicação; os dados podem ser enviados a um serviço de métricas, como o OpenTelemetry Collector. | É uma opção natural quando o projeto já usa OpenTelemetry ou precisa integrá-lo ao caminho existente de exportação e coleta. A documentação recomenda que bibliotecas dependam apenas da API, enquanto a aplicação usa API e SDK. |
OpenTelemetry PHP lista instrumentos como counter, async counter, histogram, async gauge, up/down counter e async up/down counter. Antes de instalar, confira os requisitos atuais na documentação oficial: versões de PHP suportadas mudam, e o SDK visa acompanhar as versões oficialmente suportadas, removendo suporte para versões até 12 meses após o fim de vida delas.
Free tools Windows power users keep installed
One-click scans. No signup required.
Use o tipo de métrica que corresponde ao dado
| Instrumento | Use para | Exemplo |
|---|---|---|
| Counter | Um total que só aumenta, exceto quando o processo reinicia. | Tarefas concluídas ou requisições atendidas. |
| Gauge | Uma medição ou estado atual que pode subir ou descer. | Trabalhos em andamento ou uso atual de memória. |
| Histogram | Registrar observações em intervalos configuráveis e agregar sua distribuição e soma. | Duração de requisições ou tamanho de resposta. |
Essas semânticas seguem a documentação de tipos de métricas do Prometheus. Não use counter para um valor que pode diminuir: um gauge representa melhor esse estado. Para examinar o ritmo de aumento de um counter no Prometheus, use rate(), conforme a orientação de instrumentação.
#1 Best Overall
Escolha limites do histogram pela pergunta
Os buckets determinam como as observações serão agrupadas. Para latência, por exemplo, escolha limites que ajudem a responder à pergunta real do painel ou alerta, em vez de adotar uma lista universal sem conhecer a distribuição da aplicação. A documentação do Prometheus recomenda que autores de bibliotecas permitam escolher buckets manualmente e que eles não mudem depois que a métrica for criada.
Planeje nomes, labels e armazenamento
- Defina o evento ou estado. Especifique o que quer observar antes de escolher o nome da métrica.
- Use nomes estáveis e descrições claras. A documentação do Prometheus recomenda evitar nomes dinâmicos para métricas.
- Adicione labels apenas para dimensões úteis. Se houver labels, mantenha os mesmos nomes de label em todas as séries daquela métrica. Prefira valores de conjunto controlado; IDs de usuário, caminhos arbitrários e texto livre podem gerar cardinalidade alta e crescimento descontrolado de séries.
- Escolha buckets com intenção. Defina os limites do histogram conforme a distribuição e a análise pretendida; não os altere depois da criação da métrica.
- Confirme o ciclo de vida dos dados. Verifique o adaptador de armazenamento, como as métricas são expostas e qual componente coleta ou exporta os valores.
A recomendação oficial sobre labels é começar sem elas se ainda não houver uma necessidade concreta: “If you are unsure, start with no labels and add more labels over time as concrete use cases arise.” (Prometheus: instrumentação.)
Rank #2
Registre as métricas com PromPHP
O exemplo abaixo mostra a forma dos métodos documentados pelo cliente: inc ou incBy para counter, set para gauge e observe para histogram. Ajuste a inicialização do armazenamento ao adaptador escolhido e confirme a versão instalada do pacote e sua API antes de copiar o exemplo para produção.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute<?php
// $counter, $gauge e $histogram representam métricas
// registradas com o adaptador de armazenamento escolhido.
$counter->inc(); // um evento concluído
$counter->incBy(3); // três eventos concluídos
$gauge->set(4); // estado atual: quatro trabalhos em andamento
$histogram->observe(0.42); // uma observação, por exemplo duração em segundos
Ao registrar o histogram, defina buckets apropriados para as observações que serão feitas. O cliente também aceita labels; mantenha seus nomes consistentes e seus valores controlados.
Quick Recap
Rank #4
Evite métricas que desaparecem ou perdem utilidade
- Inicialize counters em zero, conforme as diretrizes do Prometheus para bibliotecas cliente.
- Use gauge para valores que podem diminuir e counter para eventos acumulados; aplique
rate()quando precisar analisar a taxa de aumento de um counter no Prometheus. - Não presuma que métricas persistem entre requisições. Em PHP, confirme o modelo de execução e o adaptador: a observação do PromPHP sobre o adaptador em memória é específica a scripts ou processos longos e não garante persistência em uma aplicação web de curta duração.
- Evite nomes dinâmicos e labels com valores arbitrários, que podem multiplicar séries sem uma dimensão analítica útil.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
