O desenvolvimento de APIs com Delphi utilizando o Horse revolucionou a forma como criamos serviços rápidos, minimalistas e eficientes. No entanto, à medida que nossas aplicações crescem e passam a rodar em ambientes de produção complexos, surge um grande desafio: como saber exatamente o que está acontecendo por debaixo do capô em tempo real?

Monitorar uma aplicação em produção apenas analisando arquivos de log estáticos (ou pior, esperando o cliente reclamar de lentidão) não é mais viável. É aqui que entra a Observabilidade e seus pilares principais: a coleta de métricas e o rastreamento distribuído (Distributed Tracing).

Para preencher essa lacuna no ecossistema Delphi, desenvolvi dois novos middlewares que trazem suporte de primeira classe para telemetria no Horse: o horse-opentelemetry e o horse-prometheus. Neste artigo, vou explicar o que cada um faz, como eles se aplicam no seu dia a dia e como começar a usá-los agora mesmo.

O Desafio: Viabilizando a Telemetria Nativa e Eficiente no Delphi

Trazer padrões modernos de observabilidade como o OpenTelemetry e o Prometheus para o ecossistema Delphi exigiu um esforço significativo de design e arquitetura. O principal desafio foi garantir que a instrumentação ocorresse de forma extremamente leve e thread-safe. Em ambientes de alta concorrência, o gerenciamento de escopos de rastreamento e a alocação de memória precisam ser cirúrgicos para evitar degradação de performance do servidor HTTP ou vazamentos de memória.

Para que isso funcionasse perfeitamente no Horse, trabalhamos para garantir que os middlewares pudessem interceptar o fluxo da requisição desde o momento exato em que ela toca o socket até o envio final da resposta, independentemente do provedor de transporte utilizado (seja Indy, CrossSocket ou HTTP.sys). O resultado é uma integração agnóstica e de baixíssima latência, permitindo que desenvolvedores Delphi adotem as melhores práticas de engenharia de confiabilidade do mercado sem abrir mão da performance que o framework já entrega.

Por que Telemetria importa no seu dia a dia?

Imagine que sua API Delphi começou a responder de forma lenta em um determinado horário do dia. Sem telemetria, sua rotina de investigação envolveria:

• Vasculhar arquivos de logs gigantescos em busca de exceções.
• Tentar adivinhar se o gargalo é no banco de dados, no consumo de CPU da máquina ou na rede.
• Testar cenários localmente tentando reproduzir a lentidão sem sucesso.

Com telemetria ativa, você tem painéis visuais ricos que mostram exatamente:

1. Quantas requisições seu servidor está recebendo por segundo (RPS).
2. Quais endpoints estão lentos e qual etapa exata da requisição está demorando (ex: a query SQL levou 80% do tempo total).
3. A taxa de erro (status HTTP 5xx) correlacionada com picos de tráfego.

1. Coleta de Métricas com o horse-prometheus

O Prometheus é o padrão da indústria para monitoramento e alertas de infraestrutura e serviços. Ele coleta métricas da sua aplicação através de consultas periódicas (scraping) a um endpoint do seu servidor.

O middleware horse-prometheus automatiza todo esse processo no Horse. Ele coleta silenciosamente os dados de todas as requisições (como contador de requisições por método e status HTTP, e histogramas do tempo de resposta) e expõe essas informações no padrão ideal para o Prometheus consumir.

Como implementar em minutos:

Primeiro, instale a dependência via Boss:

boss install regyssilveira/horse-prometheus

Em seguida, declare o middleware no arquivo principal do seu servidor Horse:

uses
  Horse,
  Horse.Prometheus;

begin
  // Adiciona o coletor de métricas ao pipeline global
  THorse.Use(THorsePrometheus.New);

  THorse.Get('/api/v1/users',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      Res.Send('{"status": "ok"}');
    end);

  THorse.Listen(9000);
end.

O middleware irá expor automaticamente o endpoint /metrics (ou outro caminho configurável). A partir daí, basta configurar o Prometheus para raspar esses dados e acoplá-lo a um painel no Grafana para gerar gráficos de performance em tempo real.

2. Rastreamento Distribuído com o horse-opentelemetry

Enquanto o Prometheus te dá uma visão macro da aplicação (ex: “a latência média subiu”), o OpenTelemetry (OTel) te dá a visão micro de uma requisição específica. Se sua API consome outros microsserviços ou faz consultas ao banco de dados, o OpenTelemetry permite acompanhar a jornada dessa requisição de ponta a ponta.

O middleware horse-opentelemetry gerencia a criação e a propagação de Spans e Traces. Ele injeta cabeçalhos de contexto baseados no padrão W3C e envia os dados para ferramentas de APM e coletores compatíveis com OpenTelemetry, como Jaeger, Zipkin, Elastic APM, Dynatrace ou Datadog.

Como implementar:

Instale o middleware pelo Boss:

boss install regyssilveira/horse-opentelemetry

Configure-o no início do pipeline do seu Horse:

uses
  Horse,
  Horse.OpenTelemetry;

begin
  // É recomendado registrar no início do pipeline para rastrear o fluxo completo
  THorse.Use(THorseOpenTelemetry.New('meu-servidor-delphi'));

  THorse.Get('/api/v1/orders',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      // Sua lógica de negócios aqui
      Res.Send('{"orders": []}');
    end);

  THorse.Listen(9000);
end.

Ao receber uma requisição, o middleware cria um identificador único de rastreamento (Trace ID). Se o cliente que chamou sua API já enviou um Trace ID (como uma aplicação frontend ou outro backend), o Horse continua o mesmo rastreamento, criando uma árvore de execução unificada.

O que isso agrega ao seu servidor Horse no dia a dia?

A adição dessas tecnologias eleva os servidores escritos em Horse para um nível puramente corporativo e cloud-native. Veja os benefícios práticos:

• Redução drástica do MTTR (Tempo Médio de Resolução): Quando um bug acontece, você não precisa “adivinhar”. O Trace ID te mostra o caminho exato e qual chamada externa ou banco de dados gerou o erro de forma visual.
• Alertas Proativos: Configure regras no Prometheus/Grafana para te alertar (no Telegram, Discord, Teams ou E-mail) se o tempo médio de resposta de um endpoint passar de 500ms ou se os erros HTTP 500 aumentarem de repente.
• Planejamento de Capacidade (Capacity Planning): Acompanhe gráficos históricos de requisições por segundo e uso de recursos para prever com precisão quando será necessário escalar seu servidor horizontalmente ou verticalmente.

Conclusão

Com o horse-prometheus e o horse-opentelemetry, o ecossistema Horse em Delphi ganha a robustez necessária para competir de igual para igual em infraestruturas modernas e microsserviços hospedados no Kubernetes, AWS, Azure ou Google Cloud.

Convido você a testar esses middlewares em seus projetos e a contribuir com sugestões de melhoria!

Os repositórios estão abertos no GitHub:

• 💻 regyssilveira/horse-opentelemetry
• 💻 regyssilveira/horse-prometheus