observability

# Observability

## Objetivo

Definir a estrategia de observabilidade do Communications Service de forma compativel com:

- logs em `stdout`
- metricas Prometheus em `GET /metrics`
- stack LGTM externo
- Alloy como coletor

## Estado atual do servico

Hoje o servico ja entrega:

- logs estruturados com Pino
- metricas Prometheus com `prom-client`
- `GET /health`
- `GET /ready`
- `GET /metrics`

Hoje o servico ainda nao entrega:

- tracing OpenTelemetry
- correlacao forte por `trace_id` / `span_id`
- dashboards prontos no repositorio
- alertas versionados

## Objetivo operacional

Chegar a um modelo em que:

1. `communications-server` e `communications-workers` geram logs em `stdout`
2. Alloy coleta logs Docker e envia para Loki
3. Alloy scrapeia `GET /metrics` do `communications-server`
4. Grafana consulta logs e metricas no LGTM
5. numa fase posterior, o servico passa a enviar traces OTLP para `lgtm:4317`

## Arquitetura recomendada

### Agora

- `communications-server`
  - exposto apenas para o proxy/Wildcat
  - `GET /metrics` acessivel apenas por rede interna
- `communications-workers`
  - sem exposicao publica
  - logs via `stdout`
- `redis`
  - sem exposicao publica
- `alloy`
  - coleta logs de containers
  - scrapeia metricas do `communications-server`
- `lgtm`
  - centraliza Grafana, Loki, Prometheus/Mimir e OTLP futuro

### Depois

- adicionar OpenTelemetry SDK no servico
- enviar traces OTLP para `lgtm:4317`
- adicionar dashboards e alertas versionados

## Principio importante

O melhor rollout nao comeca por trace.

Primeiro deve ficar estavel:

- metricas
- logs
- dashboards basicos
- alertas minimos

So depois vale ligar tracing.

## O que medir primeiro

### Metricas ja disponiveis

- `communications_jobs_started_total`
- `communications_jobs_completed_total`
- `communications_jobs_failed_total`
- `communications_scans_total`
- `communications_provider_requests_total`
- `communications_job_duration_seconds`

### Paineis minimos

- jobs iniciados/completados/falhos por worker
- scans de reminders e notifications
- provider requests por `provider`, `channel` e `status`
- latencia dos jobs
- disponibilidade de `/ready`

### Alertas minimos

- readiness diferente de `ready`
- aumento continuo de `communications_jobs_failed_total`
- aumento continuo de `communications_provider_requests_total{status="failure"}`
- ausencia de scans por alguns minutos

## Politica de exposicao

### Publico

- `/health`
- `/ready`
- `/docs`

### Privado

- `/metrics`
- logs
- OTLP futuro

`/metrics` nao deve ficar publico na internet.

## Integracao com o stack LGTM/Alloy

O stack informado pelo ambiente faz sentido:

- `grafana/otel-lgtm`
- `grafana/alloy`
- rede `observability`

Direcao recomendada:

1. manter `lgtm` e `alloy` em rede `observability`
2. conectar `communications-server` e `communications-workers` nessa mesma rede
3. deixar Alloy coletar:
   - logs Docker
   - metricas HTTP do `communications-server`
4. guardar tracing para a fase seguinte

## Risco principal

O maior risco agora nao e falta de ferramenta. E falta de padronizacao de rollout.

Por isso a ordem recomendada e:

1. coleta de logs
2. coleta de metricas
3. dashboards
4. alertas
5. enriquecimento de logs
6. traces OTel