Uma API responder a uma chamada não significa que sabemos como ela se comporta ao longo do dia. Quantas requisições chegaram? Qual rota ficou lenta? O aumento de tráfego trouxe mais erros? Para responder, precisamos medir o funcionamento da aplicação e observar essas medidas ao longo do tempo, sem depender apenas de alguém perceber que o sistema está demorando.

Neste tutorial vamos construir um laboratório local com o Horse, meu middleware horse-prometheus, o coletor Prometheus e o Grafana. O objetivo é chegar a um painel compreensível, passando por verificações intermediárias. Não basta copiar uma consulta e encontrar um gráfico: precisamos entender de onde o número veio e o que ele permite concluir.

O cenário principal é Windows com uma aplicação console Delphi e Docker Desktop executando contêineres Linux. Os arquivos usam Prometheus 3.5.0 e Grafana 12.2.0, versões fixadas para evitar mudanças silenciosas. O exemplo compilou no Delphi 10 Seattle com Horse 3.3.10 e middleware 1.0.1, e a coleta e os quatro gráficos foram conferidos no laboratório. Não é um ensaio de desempenho nem configuração de produção; outras plataformas não foram testadas.

1. Entenda o caminho da informação

O Horse atende às chamadas HTTP. Um middleware é uma função intermediária que participa do processamento. O horse-prometheus registra contagens e tempos e expõe essas medidas em um endereço HTTP, chamado endpoint: /metrics.

O Prometheus consulta esse endereço periodicamente, processo chamado scraping, e guarda séries temporais: sequências de valores associados a instantes. O Grafana consulta esse banco para desenhar os gráficos. Ele se conecta ao Prometheus, não diretamente ao /metrics da API.

Uma métrica tem nome e valor, podendo ter rótulos que distinguem grupos, como método, caminho e status. Um contador acumula eventos; um medidor instantâneo, chamado gauge, informa uma situação naquele instante. Antes de desenhar os gráficos, precisamos comprovar que a API realmente produz essas informações.

Diagrama elaborado para o tutorial. O Prometheus inicia a coleta; o Grafana consulta o Prometheus.

2. Prepare o ambiente

2.1. O que precisa estar instalado

Neste roteiro, o Delphi compila a aplicação no Windows. Prometheus e Grafana serão executados pelo Docker. Portanto, você não precisa procurar instaladores separados dessas duas ferramentas: seus programas virão nas imagens definidas mais adiante. Precisa de um Delphi com o Indy disponível, dos fontes do Horse e do middleware, do Docker Desktop e de uma conexão para baixar os arquivos.

Se este é seu primeiro contato, faça a preparação em um computador de desenvolvimento, sem dados de clientes. Instalar componentes do Windows pode exigir reinicialização. Salve seu trabalho antes e, em computador corporativo, confirme as permissões com a equipe responsável. Os passos de instalação abaixo seguem a documentação oficial; não reinstalei o Windows, o WSL ou o Docker para simular uma instalação limpa. A integração posterior foi executada no laboratório informado.

2.2. Entenda imagem, contêiner, serviço e volume

Uma imagem reúne arquivos e dependências usados para iniciar um programa. Um contêiner é uma instância em execução a partir dela. Pense no instalador ou pacote como aproximação da imagem, e no programa aberto como aproximação do contêiner. A analogia ajuda, mas não é perfeita: o contêiner também recebe configuração, rede e áreas de armazenamento próprias.

Aqui teremos duas imagens e dois serviços: Prometheus e Grafana. Serviço é o nome de um componente declarado no arquivo de configuração do Compose. O Docker Compose lê esse arquivo e organiza os componentes juntos. Não precisamos escrever um Dockerfile, arquivo utilizado para construir uma imagem própria: utilizaremos imagens já publicadas pelos projetos.

Um volume é uma área de dados administrada pelo Docker, independente do ciclo de vida de um contêiner. Usaremos volumes para guardar histórico e painéis. Diferentemente disso, o arquivo prometheus.yml ficará em nossa pasta e será apresentado ao contêiner por uma montagem de arquivo. Entender a diferença evita confundir apagar um programa com apagar os dados produzidos por ele.

Porta é um número que identifica um ponto de comunicação de rede. O endereço localhost representa o computador ou ambiente de onde a conexão parte. Assim, localhost no navegador do Windows não significa a mesma coisa que localhost dentro do Grafana. Essa distinção será importante quando cadastrarmos o endereço do Prometheus.

2.3. Prepare o WSL antes de instalar o Docker

WSL é o Subsistema do Windows para Linux. Ele permite executar um ambiente Linux no Windows e pode servir como base do Docker Desktop. Consulte os requisitos do instalador para sua versão do Windows e arquitetura. O roteiro utiliza contêineres Linux, não contêineres Windows; uma aplicação Delphi no Windows pode ser monitorada por ferramentas Linux sem ser transferida para um contêiner.

Abra o PowerShell pelo menu Iniciar e verifique o WSL:

wsl --version
wsl --list --verbose

A primeira consulta mostra a versão do aplicativo WSL; a coluna VERSION da segunda informa se cada distribuição utiliza WSL 1 ou WSL 2. São informações distintas. Caso precise instalar, a Microsoft orienta abrir o PowerShell como administrador, executar o comando abaixo e reiniciar. Isso altera componentes do sistema; não o execute apenas porque já viu a instrução, se o ambiente estiver pronto.

wsl --install

Se o WSL já estiver instalado, mas desatualizado, a documentação também orienta verificar a atualização:

wsl --update

Após uma reinicialização solicitada pelo Windows, faça as verificações novamente. Mensagens sobre virtualização precisam ser resolvidas conforme a configuração do fabricante ou pela equipe de TI. Não existe um procedimento de BIOS único para todos os computadores. Não prossiga supondo que uma janela sem erro visível prova que o ambiente está funcionando.

2.4. Instale e abra o Docker Desktop

Na página oficial de instalação do Docker Desktop, escolha o download correspondente à arquitetura do computador. Execute o instalador e, quando houver escolha de mecanismo, selecione WSL 2. As opções e permissões variam conforme a versão e o modo de instalação. Termine o assistente e reinicie se solicitado.

Depois, abra Docker Desktop pelo menu Iniciar: instalar não equivale a iniciar o aplicativo. Leia os termos e confira o licenciamento aplicável ao seu uso, principalmente em empresas. Aguarde a inicialização. Não precisamos aceitar uma oferta de serviço em nuvem para compreender o laboratório local; siga as exigências legítimas do produto e de sua organização.

Os comandos de operação serão executados no PowerShell do Windows, não em um terminal Ubuntu. Feche e abra novamente o PowerShell após instalar, para que ele reconheça as ferramentas. Não repita a instalação indiscriminadamente se aparecer uma mensagem de erro: primeiro identifique se o problema é o comando ausente ou o serviço ainda não iniciado.

2.5. Confirme que o Docker está funcionando

Execute os dois comandos seguintes. A saída de docker version precisa mostrar Client e Server. Client é a ferramenta que recebe o comando; Server é o mecanismo que executa os contêineres. Uma versão do cliente acompanhada de erro de conexão não representa sucesso. O segundo comando verifica o Compose, fornecido com Docker Desktop.

docker version
docker compose version

2.6. Crie a pasta e confira os nomes dos arquivos

Use uma pasta exclusiva, como laboratorio-horse dentro de Documentos. Você pode criá-la pelo Explorador de Arquivos. Para quem preferir o terminal, estes comandos criam a pasta convencional de Documentos do perfil e entram nela. Se Documentos estiver redirecionado para outra localização, adapte o caminho ao local escolhido:

New-Item -ItemType Directory -Path "$env:USERPROFILE\Documents\laboratorio-horse" -Force
Set-Location -LiteralPath "$env:USERPROFILE\Documents\laboratorio-horse"
Get-Location

Get-Location informa a pasta atual. Depois de salvar os arquivos apresentados na etapa 5, use Get-ChildItem para conferir se compose.yaml e prometheus.yml estão exatamente nessa pasta. Esse cuidado elimina o erro de executar o Compose no diretório errado. Um caminho com espaços deve permanecer entre aspas.

Ao usar o Bloco de Notas, escolha Todos os arquivos no tipo de salvamento e mantenha os nomes completos. Confira a extensão no Explorador: compose.yaml.txt não é compose.yaml. Faça o mesmo com prometheus.yml. Salve em UTF-8 e preserve a indentação dos exemplos. Não copie os delimitadores de um bloco de código nem a palavra yaml para dentro do arquivo.

2.7. Prepare as bibliotecas e o projeto Delphi

Crie uma pasta exclusiva para o laboratório. Não utilize um projeto real de cliente. Reserve as portas 9000 para a API, 9090 para o Prometheus e 3000 para o Grafana. Se alguma estiver ocupada, identifique o serviço antes de interrompê-lo ou altere consistentemente a configuração do tutorial. Uma mensagem de porta ocupada não é defeito do middleware.

Obtenha o Horse 3.3.10 e o horse-prometheus. No GitHub, use Code e Download ZIP, extraia os arquivos e renomeie as pastas para horse e horse-prometheus. Dentro da pasta do laboratório, organize-as assim:

laboratorio/
  Tutorial.dpr
  horse/
    src/Horse.pas
  horse-prometheus/
    Horse.Prometheus.pas
  prometheus.yml
  compose.yaml

O provedor é a camada que realiza o transporte HTTP. Usaremos o padrão com Indy, disponível no ambiente Delphi testado, sem definir símbolos para outros provedores. Confira que os arquivos mostrados existem após a extração: uma pasta duplicada dentro do ZIP pode mudar os caminhos.

No Delphi, abra Project, Options, Delphi Compiler e Search path, selecionando Win32 e a configuração utilizada. Acrescente $(PROJECTDIR)horse\src e $(PROJECTDIR)horse-prometheus, separados por ponto e vírgula. $(PROJECTDIR) representa a pasta do projeto. Informe diretórios, não nomes de executáveis. Se não encontrar Horse ou Horse.Prometheus, confira esses caminhos. Uma unidade IdHTTPWebBrokerBridge ausente exige verificar a instalação do Indy, não baixar arquivos aleatórios.

Para este roteiro, a instalação manual mantém os caminhos nas opções do projeto e dispensa alterações na configuração global da IDE. Quem utiliza um gerenciador de dependências pode manter seu fluxo habitual, mas deve conferir as versões e os diretórios efetivamente utilizados na compilação.

Para aprofundar a organização dessas bibliotecas, veja o artigo sobre pacotes verificáveis no Boss4D. Aqui, o foco permanece na conexão entre aplicação e monitoramento, independentemente do gerenciador escolhido.

3. Crie a aplicação console

No Delphi, crie uma aplicação console e salve como Tutorial.dpr. Substitua o código principal pelo exemplo completo abaixo. /ping responde rapidamente. /lento acrescenta uma espera didática de 200 milissegundos. /falha devolve intencionalmente o código 500, representando erro do servidor. Esses recursos existem para tornar a demonstração visível, não para serem copiados para produção.

program Tutorial;
{$APPTYPE CONSOLE}
uses
  System.SysUtils, System.Classes, Horse, Horse.Prometheus;
begin
  THorse.Use(THorsePrometheus.Middleware());
  THorse.Get('/ping',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('pong');
    end);
  THorse.Get('/lento',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      TThread.Sleep(200);
      Res.Send('resposta com atraso didatico');
    end);
  THorse.Get('/falha',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Status(500).Send('falha simulada');
    end);
  Writeln('API em http://localhost:9000/ping');
  Writeln('Metricas em http://localhost:9000/metrics');
  THorse.Listen(9000);
end.

Registre o middleware antes das rotas. Ele mede o processamento posterior à chamada de continuação, chamada Next. Em projetos com autenticação e tratamento de exceções, examine a ordem desses componentes para que a medida e o status representem o comportamento desejado. Nosso erro demonstrativo define explicitamente uma resposta; não lança uma exceção.

Compile, execute e mantenha o processo ativo. Abra http://localhost:9000/ping no navegador: deve aparecer pong. Se a aplicação fechar ou a conexão falhar, resolva essa etapa antes de continuar. Nenhum ajuste na fonte de dados do Grafana faz uma API parada começar a responder.

4. Confira o endpoint de métricas

Depois de visitar /ping, abra http://localhost:9000/metrics. A resposta é texto, não JSON nem uma página de gráficos. Procure http_requests_total e as séries http_request_duration_seconds_sum e http_request_duration_seconds_count. O próprio acesso a /metrics é interceptado antes da contagem das chamadas de negócio, conforme a implementação.

Faça novas chamadas e atualize a página. O contador de /ping deve aumentar. O valor exato depende de suas chamadas; uma captura não é um número universal. Reiniciar o executável reinicia seus contadores em memória. O histórico coletado pelo Prometheus pertence a outra camada e não desaparece simplesmente porque a aplicação reiniciou.

O sufixo _sum representa a soma dos tempos, em segundos; _count representa a quantidade de observações. Podemos obter uma média, mas essa implementação não expõe histogramas nem quantis que permitam apresentar p95 ou p99. Esses percentis descrevem a distribuição dos tempos, não a média; consulte a documentação de histogramas e resumos.

Na versão examinada, a exportação arredonda a soma dos tempos para duas casas decimais. Valores muito pequenos podem aparecer como zero por arredondamento, não por processamento instantâneo. O atraso de /lento ajuda a observar uma diferença visível sem transformar o tutorial em uma medição de alta precisão.

5. Configure e inicie o Prometheus e o Grafana

Salve este conteúdo em prometheus.yml na pasta do laboratório. YAML depende da indentação: preserve os espaços e não use tabulações. horse-api é o nome do grupo de coleta, chamado job. Cinco segundos é uma escolha didática, não uma recomendação universal para servidores de qualquer tamanho.

global:
  scrape_interval: 5s
scrape_configs:
  - job_name: horse-api
    metrics_path: /metrics
    static_configs:
      - targets: ['host.docker.internal:9000']

O Prometheus roda dentro do Docker Desktop e a API no Windows. Por isso o alvo não é localhost:9000, que apontaria para o próprio contêiner. Usamos host.docker.internal para alcançar o hospedeiro. Uma instalação Linux sem Docker Desktop pode exigir outra solução de rede; este arquivo não pretende cobrir todas as topologias.

Ao lado dele, salve compose.yaml com o conteúdo abaixo. Os volumes guardam dados do Prometheus e do Grafana entre recriações dos serviços. A configuração do Prometheus é montada somente para leitura. A publicação em 127.0.0.1 limita as interfaces ao computador local, diferentemente da exposição em todas as interfaces. Veja a documentação de rede do Docker Desktop.

services:
  prometheus:
    image: prom/prometheus:v3.5.0
    ports:
      - "127.0.0.1:9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus-dados:/prometheus
  grafana:
    image: grafana/grafana:12.2.0
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      GF_USERS_ALLOW_SIGN_UP: "false"
    volumes:
      - grafana-dados:/var/lib/grafana
volumes:
  prometheus-dados:
  grafana-dados:

No PowerShell, dentro dessa pasta, execute os comandos seguintes. config ajuda a detectar problemas de sintaxe antes de iniciar os serviços. A primeira subida baixa as imagens, podendo demorar. Confira os dois serviços em execução com ps; se um sair imediatamente, examine seus registros com logs antes de repetir comandos.

docker compose -p tutorial-horse-metricas config
docker compose -p tutorial-horse-metricas up -d
docker compose -p tutorial-horse-metricas ps
docker compose -p tutorial-horse-metricas logs --tail 50

5.1. O que cada comando faz

Na inicialização com Compose, a pasta e o nome do projeto fazem parte da organização do ambiente. Neste tutorial, mantenha sempre o mesmo nome depois de -p: tutorial-horse-metricas. Isso separa nossos serviços de outros projetos existentes no Docker. Não alterne comandos com e sem esse parâmetro ao acompanhar os passos.

config lê e confere o arquivo, exibindo sua configuração interpretada. Não inicia os serviços. Se indicar arquivo ausente, confira a pasta e a extensão; se mostrar erro de YAML, procure a linha indicada e verifique os espaços. Não tente corrigir isso reinstalando o Docker.

up -d cria e inicia os serviços em segundo plano. O parâmetro -d permite continuar usando o PowerShell, em vez de deixar o terminal ocupado mostrando os registros. Na primeira execução, o Docker baixa as imagens necessárias; nas seguintes pode reutilizar as já presentes. A velocidade depende da conexão e dos arquivos, portanto não espere uma duração fixa.

ps mostra o estado dos serviços. Procure prometheus e grafana em execução. As portas devem relacionar 127.0.0.1:9090 com 9090 e 127.0.0.1:3000 com 3000. A primeira parte representa o acesso no Windows; a segunda, a porta do programa dentro do contêiner. Um contêiner iniciado ainda pode precisar de alguns segundos para a aplicação ficar pronta.

logs –tail 50 mostra os registros mais recentes. Para examinar apenas um serviço, acrescente seu nome:

docker compose -p tutorial-horse-metricas logs --tail 50 prometheus
docker compose -p tutorial-horse-metricas logs --tail 50 grafana

Abra agora http://localhost:9090 e http://localhost:3000 no navegador do Windows. O primeiro deve abrir a interface do Prometheus e o segundo, a do Grafana. Essa conferência testa a disponibilidade das ferramentas; o alvo UP, na etapa seguinte, verifica outra coisa: se o Prometheus consegue coletar a API.

5.2. Se a primeira execução não funcionar

Se docker não for reconhecido, confirme a instalação e abra um novo PowerShell. Se o cliente existir, mas não conseguir acessar o mecanismo, confira Docker Desktop aberto e a inicialização do WSL. Se a imagem não puder ser baixada, leia a mensagem e verifique conexão, proxy e políticas corporativas. Não desative proteções para forçar um download.

Se aparecer porta ocupada, verifique qual programa já utiliza 3000 ou 9090. Não encerre processos desconhecidos. Uma alternativa é mudar somente a porta do Windows no arquivo Compose, por exemplo de 3000 para 3001, e acessar localhost:3001. A porta interna do Grafana continua 3000. As demais instruções deste artigo presumem os números originais.

Se o Prometheus reclamar que a configuração não é um arquivo válido, confira prometheus.yml no local certo antes de subir novamente. A montagem definida no Compose depende desse arquivo. Depois de corrigir, repita up -d e ps. Não apague volumes para resolver um erro de nome ou indentação.

6. Verifique a coleta antes de criar gráficos

Abra http://localhost:9090/targets. O grupo horse-api deve ter um alvo em estado UP. Isso demonstra sucesso na consulta de métricas, não sucesso em toda operação de negócio. Uma API pode expor /metrics enquanto determinada rota devolve um erro.

Se estiver DOWN, leia a mensagem do alvo e confira API ativa, porta e endereço. Teste /metrics no Windows e depois examine as restrições de rede. Não desligue o firewall como solução genérica: autorize apenas o tráfego necessário conforme as regras de seu ambiente. Prove o acesso antes de passar para a próxima ferramenta.

Na página Query do Prometheus, consulte up{job="horse-api"}; o alvo acessível deve apresentar 1. Depois consulte http_requests_total{job="horse-api"}. Se não existirem séries, gere chamadas nas rotas e aguarde as próximas coletas. O status da coleta e a existência de tráfego são verificações distintas.

Captura do laboratório: coleta bem-sucedida em host.docker.internal:9000/metrics.

7. Cadastre a fonte de dados no Grafana

Abra http://localhost:3000. Em um volume novo, o acesso inicial utiliza usuário e senha admin; defina uma senha própria quando solicitado. Credenciais já alteradas permanecem no volume. Portanto, esse acesso inicial não recupera uma instalação antiga nem justifica deixar uma senha padrão em produção.

Siga Connections, Add new connection, procure Prometheus e selecione Add new data source. Os nomes em inglês permitem localizar os controles. Use Prometheus Horse como nome e http://prometheus:9090 como Prometheus server URL. prometheus é o serviço definido no Compose, acessível pela rede compartilhada dos contêineres.

Informe cinco segundos como intervalo de coleta e pressione Save & test. A confirmação deve indicar consulta bem-sucedida à API do Prometheus. localhost:9090 seria incorreto nesse cenário porque aponta para o contêiner Grafana. A documentação da fonte de dados explica essa distinção e a verificação da conexão.

Captura do laboratório. O endereço é visto a partir do Grafana dentro do Docker.

Confirmação obtida com Save & test no laboratório.

8. Gere tráfego e monte as visualizações

Execute este laço no PowerShell enquanto a API permanece aberta. As chamadas são sequenciais: não simulam usuários simultâneos nem medem capacidade máxima. A resposta 500 de /falha é intencional. curl.exe recebe essa resposta HTTP, que não deve ser confundida com falha de conexão. O nome explícito evita apelidos do PowerShell.

1..120 | ForEach-Object {
    curl.exe -s http://localhost:9000/ping | Out-Null
    curl.exe -s http://localhost:9000/lento | Out-Null
    curl.exe -s http://localhost:9000/falha | Out-Null
    Start-Sleep -Milliseconds 500
}

Um dashboard é o painel que reúne as visualizações. Em Dashboards, use New e New dashboard, depois Add visualization e selecione Prometheus Horse. Na aba Queries, escolha Code para escrever PromQL, a linguagem do Prometheus. À direita, mantenha Time series e preencha Title com Requisições por segundo. Cole esta expressão e pressione Run queries:

sum(rate(http_requests_total{job="horse-api"}[1m]))

rate calcula a taxa por segundo a partir das amostras do contador na janela de um minuto; sum reúne as séries. Isso não representa o contador acumulado nem a quantidade exata de chamadas no último segundo. Aguarde várias coletas: uma janela com dados insuficientes pode não apresentar resultado.

Consulta executada no laboratório; valores variam conforme o tráfego.

Use Back to dashboard e Save dashboard; dê ao conjunto o nome Horse — métricas do laboratório e confirme Save. Selecione Last 15 minutes no período e 5s na atualização automática. Para acrescentar os próximos gráficos, entre em Edit, abra Add e selecione uma nova visualização. Salve novamente depois de terminar.

Adicione Respostas por código HTTP com a expressão abaixo. O agrupamento mantém separadas as respostas 200 e 500. Configure a legenda para mostrar o status. Os erros deste teste são esperados; o gráfico ensina a localizar a distribuição das respostas, mas não revela sozinho a causa de uma falha real.

Para nomear as linhas, expanda Options abaixo da consulta e preencha o campo Legend com {{status}}. No gráfico de latência, use {{route}} nesse campo. A legenda utiliza o valor do rótulo de cada série, evitando que todas apareçam com o mesmo nome. No editor à direita, Standard options, Unit permite escolher seconds (s), a unidade de segundos.

sum by (status) (rate(http_requests_total{job="horse-api"}[1m]))

Para Latência média por rota, escolha segundos como unidade e use a divisão abaixo. A média de /lento deve refletir o atraso artificial e o processamento medido. Rotas sem chamadas na janela podem não ter média definida; ausência de resultado não significa latência zero. A média também pode esconder respostas excepcionalmente lentas.

sum by (route) (rate(http_request_duration_seconds_sum{job="horse-api"}[1m]))
/
sum by (route) (rate(http_request_duration_seconds_count{job="horse-api"}[1m]))

Na quarta visualização, use http_active_requests{job="horse-api"} e escolha Stat para mostrar o último valor. A coleta pode acontecer entre chamadas e mostrar zero mesmo com tráfego. Essa é uma medida instantânea, não o total de requisições do período. O laço sequencial não permite concluir qual concorrência a API suporta.

Captura do laboratório. A rota /lento evidencia o atraso artificial e /falha produz respostas 500 deliberadamente.

9. Conheça os limites e pare o laboratório

O rótulo de rota usa o caminho recebido. Identificadores diferentes podem gerar muitas séries, problema chamado cardinalidade. Antes de levar a coleta para produção, examine caminhos, privacidade, normalização, autenticação e retenção. Proteja /metrics e as interfaces administrativas. Uma configuração local funcional não é um projeto completo de segurança e operação.

A porta 9000 não recebeu a restrição de publicação aplicada aos contêineres. Não execute essa API demonstrativa em servidor público nem presuma que a configuração do Compose protege todas as portas do Windows. Verifique as regras locais sem desativar o firewall. Também não mantenha a rota de erro artificial em uma aplicação real.

Aplicações com conexões prolongadas merecem outra análise: o artigo sobre transmissão contínua e eventos no Horse apresenta esse cenário. Não extrapole a duração das três respostas curtas deste laboratório para essas conexões.

Para parar somente este laboratório, execute o comando abaixo na pasta do Compose. Ele não utiliza -v, opção que removeria os volumes. Pare também a aplicação console. Uma próxima subida reutiliza os dados dos volumes, enquanto o executável inicia novamente os contadores em memória.

docker compose -p tutorial-horse-metricas down

9.1. Como usar o laboratório em outro dia

Depois de uma reinicialização do Windows, abra Docker Desktop, aguarde o mecanismo funcionar e execute novamente a aplicação Delphi. Entre na pasta do laboratório pelo PowerShell e utilize up -d com o mesmo nome de projeto. Confirme ps, depois o alvo UP e a fonte de dados. Os gráficos precisam de novas coletas para representar a sessão atual.

Se quiser apenas interromper os contêineres, preservando sua existência, use stop. Para iniciar esses mesmos contêineres novamente, use start:

docker compose -p tutorial-horse-metricas stop
docker compose -p tutorial-horse-metricas start

down, mostrado acima, remove os contêineres e a rede criada pelo projeto. Uma próxima execução de up -d os recria. Os volumes nomeados permanecem quando não utilizamos -v; por isso os painéis e dados armazenados neles podem ser reaproveitados. Não confunda o reinício da API, que zera seus contadores em memória, com a remoção do armazenamento do Prometheus.

Não use comandos gerais de limpeza, como apagar todos os volumes do Docker, para arrumar este exemplo. Outros projetos podem depender deles. Antes de uma exclusão, identifique o recurso e tenha cópia do que precisa preservar. Encerrar nosso laboratório não deve interromper serviços alheios.

9.2. Confira o caminho completo antes de encerrar

Você deve conseguir explicar cinco verificações: /ping responde pong; /metrics fornece texto de métricas; o alvo horse-api está UP; Save & test confirma a fonte Prometheus; os gráficos mostram as chamadas geradas. Se uma delas falhar, retorne à etapa correspondente. Um problema no início da cadeia não se resolve ajustando a cor ou o título de um gráfico no final.

Guarde os dois arquivos YAML e o projeto Delphi. Eles descrevem o laboratório, mas não substituem um backup dos dados dos volumes. Se compartilhar os arquivos, não inclua senhas próprias, tokens ou dados de clientes. As capturas deste artigo mostram informações demonstrativas e não uma instalação produtiva.

Conclusão

O caminho confiável começa com /ping, passa por /metrics, pelo alvo UP e pelo teste da fonte de dados, e só então chega aos gráficos. Quando um painel fica vazio, retornar à última etapa comprovada costuma ser melhor do que modificar consultas aleatoriamente. Cada verificação elimina uma classe de problemas.

O laboratório oferece uma base para acompanhar tráfego, erros e latência média de uma API Horse. Não substitui testes de negócio, registros de eventos ou rastreamento distribuído, nem garante execução sem erros em qualquer computador. O ganho é relacionar perguntas operacionais a medidas verificáveis, reconhecendo os limites de cada número exibido.

Referências

DOCKER INC. Docker Compose Quickstart. Docker Docs, [s. d.]. Disponível em: https://docs.docker.com/compose/gettingstarted/. Acesso em: 4 out. 2026.

DOCKER INC. Explore networking how-tos on Docker Desktop. Docker Docs, [s. d.]. Disponível em: https://docs.docker.com/desktop/features/networking/networking-how-tos/. Acesso em: 4 out. 2026.

DOCKER INC. Install Docker Desktop on Windows. Docker Docs, [s. d.]. Disponível em: https://docs.docker.com/desktop/setup/install/windows-install/. Acesso em: 4 out. 2026.

DOCKER INC. Networking on Docker Desktop. Docker Docs, [s. d.]. Disponível em: https://docs.docker.com/desktop/features/networking/. Acesso em: 4 out. 2026.

DOCKER INC. Volumes. Docker Docs, [s. d.]. Disponível em: https://docs.docker.com/engine/storage/volumes/. Acesso em: 4 out. 2026.

DOCKER INC. What is a container? Docker Docs, [s. d.]. Disponível em: https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/. Acesso em: 4 out. 2026.

DOCKER INC. What is an image? Docker Docs, [s. d.]. Disponível em: https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/. Acesso em: 4 out. 2026.

GRAFANA LABS. Configure the Prometheus data source. Grafana documentation, 4 ago. 2026. Disponível em: https://grafana.com/docs/grafana/latest/datasources/prometheus/configure/. Acesso em: 4 out. 2026.

HASHLOAD. Horse: versão 3.3.10. GitHub, [s. d.]. Disponível em: https://github.com/HashLoad/horse/tree/3.3.10. Acesso em: 4 out. 2026.

HASHLOAD. Horse. GitHub, [s. d.]. Disponível em: https://github.com/HashLoad/horse. Acesso em: 4 out. 2026.

MICROSOFT. Como instalar o Linux no Windows com o WSL. Microsoft Learn, [s. d.]. Disponível em: https://learn.microsoft.com/pt-br/windows/wsl/install. Acesso em: 4 out. 2026.

PROMETHEUS AUTHORS. Getting started. Prometheus, [s. d.]. Disponível em: https://prometheus.io/docs/prometheus/latest/getting_started/. Acesso em: 4 out. 2026.

PROMETHEUS AUTHORS. Histograms and summaries. Prometheus, [s. d.]. Disponível em: https://prometheus.io/docs/practices/histograms/. Acesso em: 4 out. 2026.

PROMETHEUS AUTHORS. Query functions. Prometheus, [s. d.]. Disponível em: https://prometheus.io/docs/prometheus/latest/querying/functions/. Acesso em: 4 out. 2026.

SILVEIRA, Régys Borges da. Boss4D 1.6.0: Registry v2, pacotes verificáveis e paridade real no Linux. Régys Borges da Silveira, [s. d.]. Disponível em: https://regys.com.br/boss4d-1-6-0-registry-v2-pacotes-verificaveis-e-paridade-real-no-linux/. Acesso em: 4 out. 2026.

SILVEIRA, Régys Borges da. Horse Streaming: Elevando a performance de APIs Delphi e Lazarus com Web Streams e Server-Sent Events (SSE). Régys Borges da Silveira, 17 jul. 2026. Disponível em: https://regys.com.br/horse-streaming-elevando-a-performance-de-apis-delphi-e-lazarus-com-web-streams-e-server-sent-events-sse/. Acesso em: 4 out. 2026.

SILVEIRA, Régys Borges da. horse-prometheus: revisão 0007475. GitHub, [s. d.]. Disponível em: https://github.com/regyssilveira/horse-prometheus/tree/0007475d9baa4e18ca19a7d94fcc8a96c322ae08. Acesso em: 4 out. 2026.

SILVEIRA, Régys Borges da. horse-prometheus. GitHub, [s. d.]. Disponível em: https://github.com/regyssilveira/horse-prometheus. Acesso em: 4 out. 2026.

SILVEIRA, Régys Borges da. Horse.Prometheus.pas. GitHub, [s. d.]. Disponível em: https://github.com/regyssilveira/horse-prometheus/blob/master/Horse.Prometheus.pas. Acesso em: 4 out. 2026.