Métricas Customizadas: Prometheus + Grafana no Linux

O que são Métricas Customizadas e Por Que Elas Importam

No ecossistema moderno de observabilidade, confiar exclusivamente nas métricas padrão do sistema operacional — como uso de CPU, memória RAM e I/O de disco — é uma estratégia insuficiente para garantir a saúde real das aplicações. Essas métricas infraestruturais dizem apenas se o servidor está "vivo", mas não revelam se a aplicação está funcionando corretamente sob a perspectiva do usuário final ou do negócio.

Muitas vezes, o gargalo de desempenho não reside na infraestrutura subjacente, mas sim na lógica de negócios, em integrações externas lentas ou em vazamentos de memória dentro do código. É aqui que as métricas customizadas se tornam essenciais: são dados específicos coletados diretamente da sua aplicação que revelam como o software performa sob diferentes cargas e cenários. Elas permitem capturar KPIs (Indicadores-Chave de Desempenho) de domínio, como carrinhos abandonados em um e-commerce, filas de processamento assíncrono não atendidas ou taxas de erro específicas por tipo de transação.

O Prometheus consolidou-se como o padrão da indústria para coleta e armazenamento de séries temporais (TSDB). Diferente de sistemas tradicionais baseados em push, o Prometheus opera em um modelo de pull, onde o servidor de monitoramento busca ativamente os dados expostos pelos serviços-alvo. Para coletar métricas que não são nativas do sistema operacional, utilizamos o conceito de exportadores ou bibliotecas client-side. Este tutorial demonstra como criar um exportador simples em Python para expor dados de uma aplicação fictícia e visualizá-los no Grafana, estabelecendo as bases para uma estratégia robusta de monitoramento vps e aplicações.

Arquitetura da Solução

Antes de executar os comandos, é crucial entender o fluxo de dados entre os componentes que compõem a pilha de monitoramento. A arquitetura proposta segue o padrão industrial de separação de responsabilidades:

• Aplicação (Exporter): Um script Python ou binário que roda localmente e expõe uma URL HTTP (geralmente na porta 9100 ou similar) no formato /metrics. Este componente atua como a fonte da verdade, expondo os dados brutos no formato textual legível pelo Prometheus. A instrumentação é feita diretamente no código da aplicação.
• Prometheus Server: Configura periodicamente para buscar os dados dessa URL via HTTP GET. Ele armazena esses dados em disco local (TSDB) e permite consultas complexas usando sua linguagem própria, PromQL. O servidor gerencia a descoberta de alvos e a retenção dos dados.
• Grafana: Conecta-se ao Prometheus como fonte de dados principal. Ele não armazena métricas por si só, mas as consulta em tempo real para renderizar gráficos interativos, tabelas e alertas. É a camada de apresentação da observabilidade.

Essa separação permite flexibilidade operacional. Você pode trocar o banco de dados Prometheus por um sistema compatível com o protocolo OpenMetrics sem alterar seu código de aplicação. Da mesma forma, pode mudar a ferramenta de visualização (para InfluxDB, Datadog, etc.) sem mexer na coleta de dados, desde que o exportador continue expondo os dados no formato padrão.

Pré-requisitos

Para seguir este tutorial com sucesso e garantir um ambiente de teste estável, você precisará atender aos seguintes requisitos técnicos:

• Um servidor Linux (Ubuntu 20.04/22.04 ou Debian 11/12) com acesso root ou usuário sudo.
• Python 3 instalado e configurado no PATH global.
• Conhecimento básico de linha de comando Linux, gerenciamento de serviços (systemd) e conceitos de redes (HTTP, portas, firewalls).
• Acesso a um navegador web para configurar o Grafana.
• Um firewall configurado (UFW ou iptables) liberando as portas necessárias (9090 para Prometheus, 3000 para Grafana e 8080 para o exporter).

Este ambiente pode ser uma máquina virtual na nuvem ou um VPS dedicado. Ter controle total sobre o sistema operacional permite ajustar parâmetros de kernel e permissões que são críticos para o desempenho do monitoramento em produção.

Passo 1: Preparando o Ambiente

Vamos começar preparando o sistema operacional. Para este exemplo, simularemos a coleta de uma métrica customizada chamada app_requests_total, que conta quantas requisições foram processadas pela aplicação ao longo do tempo.

Instale as dependências básicas do sistema e o Python 3:

sudo apt update
sudo apt install python3 python3-pip curl wget -y

O Prometheus pode ser instalado via pacote binário oficial ou Docker. Para simplificar este tutorial e focar na configuração manual e na compreensão interna do funcionamento, utilizaremos a instalação via binário pré-compilado em um diretório dedicado. Isso oferece maior transparência sobre o que está acontecendo no sistema, facilitando o troubleshooting.

Passo 2: Instalando e Configurando o Prometheus

Por questões de segurança e boas práticas de isolamento de privilégios, nunca execute serviços de monitoramento como usuário root. Crie um usuário específico para rodar o serviço:

sudo useradd --no-create-home --shell /bin/false prometheus

Crie os diretórios de configuração e dados persistentes para separar os arquivos estáticos dos dados dinâmicos:

sudo mkdir /etc/prometheus
sudo mkdir /var/lib/prometheus

Baixe a versão mais recente estável do Prometheus. Verifique sempre o site oficial para a última versão, mas o exemplo abaixo ilustra o processo genérico com a versão 2.47.0:

cd /tmp
wget https://github.com/prometheus/prometheus/releases/download/v2.47.0/prometheus-2.47.0.linux-amd64.tar.gz
tar xvfz prometheus-2.47.0.linux-amd64.tar.gz

Mova os binários e arquivos de configuração para seus locais definitivos, garantindo que estejam acessíveis ao sistema:

sudo cp prometheus-2.47.0.linux-amd64/prometheus /usr/local/bin/
sudo cp prometheus-2.47.0.linux-amd64/promtool /usr/local/bin/
sudo cp -r prometheus-2.47.0.linux-amd64/consoles /etc/prometheus
sudo cp -r prometheus-2.47.0.linux-amd64/console_libraries /etc/prometheus

Agora, defina as permissões corretas para que o usuário prometheus possa acessar e escrever em seus próprios arquivos sem necessidade de elevação de privilégios:

sudo chown prometheus:prometheus /usr/local/bin/prometheus
sudo chown prometheus:prometheus /usr/local/bin/promtool
sudo chown -R prometheus:prometheus /etc/prometheus
sudo chown -R prometheus:prometheus /var/lib/prometheus

Configurando o Arquivo YAML

Crie o arquivo de configuração /etc/prometheus/prometheus.yml. Este arquivo instrui o Prometheus onde buscar as métricas e como interpretá-las. A estrutura YAML deve ser rigorosa quanto à indentação, pois erros aqui impedirão o início do serviço.

sudo tee /etc/prometheus/prometheus.yml > /dev/null <

sudo pip3 install prometheus_client

sudo tee /opt/custom_exporter.py > /dev/null <<'PYTHON_CODE'
from prometheus_client import start_http_server, Counter, Histogram, Gauge
import time
import random

# 1. Definir as métricas customizadas
# Counter: Métrica que só aumenta (ex: total de requisições)
app_requests_total = Counter('app_requests_total', 'Total number of requests processed')

# Histogram: Mede a duração das requisições (latência)
request_duration = Histogram('app_request_duration_seconds', 'Duration of requests in seconds')

# Gauge: Métrica que sobe e desce (ex: número de usuários ativos)
active_users = Gauge('app_active_users', 'Number of active users')

def simulate_work():
    """Simula o processamento de uma requisição"""
    start_time = time.time()
    
    # Simula tempo de processamento aleatório entre 0.1s e 0.5s
    time.sleep(random.uniform(0.1, 0.5))
    
    end_time = time.time()
    duration = end_time - start_time
    
    # Incrementa o contador de requisições
    app_requests_total.inc()
    
    # Registra a duração no histograma
    request_duration.observe(duration)
    
    return duration

def main():
    # 2. Iniciar o servidor HTTP na porta 8080
    # O endpoint /metrics será servido automaticamente pela biblioteca
    start_http_server(8080)
    print("Exporter started on port 8080...")
    
    while True:
        # Simula a chegada de requisições
        simulate_work()
        
        # Atualiza métricas gauge simulando usuários entrando e saindo
        active_users.set(random.randint(10, 100))
        
        # Aguarda um pouco antes da próxima simulação
        time.sleep(2)

if __name__ == '__main__':
    main()
PYTHON_CODE

sudo tee /etc/systemd/system/custom-exporter.service > /dev/null <

sudo systemctl daemon-reload
sudo systemctl enable custom-exporter.service
sudo systemctl start custom-exporter.service

sudo systemctl status custom-exporter.service

curl http://localhost:8080/metrics

# HELP app_requests_total Total number of requests processed
# TYPE app_requests_total counter
app_requests_total 42.0
# HELP app_request_duration_seconds Duration of requests in seconds
# TYPE app_request_duration_seconds histogram
app_request_duration_seconds_bucket{le="0.1",...} 5
app_request_duration_seconds_sum 8.5
...