Observability playbook for Rails + Puma

Observability playbook for Rails + Puma

Apps Rails com Puma precisam de visibilidade de fila, threads e latência de respostas para evitar surpresas em produção. Este playbook aponta o mínimo viável para monitorar e reagir rápido.

O que instrumentar

• Fila de requests por worker: tempo de fila (queue_time) e quantidade em espera.
• Threads ocupadas: puma_threads_count por worker para saber se falta capacidade.
• Latência por ação: percentis de controller (p50, p90, p99) e jobs.
• Erros por endpoint: taxa de 5xx e 4xx inesperados.
• Uso de memória: RSS por worker e master.

Implementação rápida

1) Rack middleware para queue time
Capture timestamps no início e fim do request e envie para Prometheus/StatsD.

2) Puma stats endpoint
Ative state_path e control_app (porta interna). Colete running, backlog, pool_capacity.

3) Logs estruturados
Logue request_id, user_id opcional, path, status, duration_ms, queue_ms. Use JSON para facilitar busca.

4) Tracing opcional
Se usar OpenTelemetry, traceie controller + ActiveRecord + external calls. Amostre 5–10% para produção moderada.

5) Alertas práticos

• queue_time_p90 > 300ms por 5 min.
• puma_backlog > 0 por 3 min.
• rss > limite por worker (evitar OOM).
• error_rate_p99 > 1%.

Playbook de resposta

• Backlog alto: aumentar workers/threads ou reduzir tempos de I/O; validar DB pool.
• Latência alta em poucos endpoints: inspecione N+1, caches, tempo externo.
• Memória subindo: revisar leaks (objeto longo), ajustar GC (RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR).
• Erro em batch: correlacione request_id com logs de dependências (DB, Redis, HTTP).