Troubleshooting

Objaw → przyczyna → naprawa. Najczęstsze problemy produkcyjne reverse proxy i jak je diagnozować metrykami oraz logami.

Tabela problemów#

Objaw	Przyczyna	Naprawa
`admin API is disabled`	`ADMIN_TOKEN` nieustawiony	Exportuj `ADMIN_TOKEN` i zrestartuj
`503 service_unavailable`	Brak zdrowego/dostępnego backendu	`GET /admin/backends`, sprawdź health checks i breakery
`502 bad_gateway`	Upstream nieosiągalny lub odrzucił	Zweryfikuj URL-e backendów i sieć
`504 gateway_timeout`	Upstream przekroczył `backend_response_header`	Zwiększ timeout albo zbadaj wolny backend
`429 rate_limit_exceeded`	Klient przekroczył limit	Dostrój `requests_per_minute` / `burst`
Klienci wyglądają jak IP load balancera	Brak trusted proxies	Ustaw `rate_limit.trusted_proxies`
Konfiguracja odrzucona przy starcie	Błąd walidacji	Błąd wymienia wszystkie nieprawidłowe pola
Błędy Redis w `rate_limit_errors_total`	Redis nieosiągalny	Sprawdź `redis.addr` / `REDIS_PASSWORD`; ruch płynie (fail-open)

Diagnoza krok po kroku#

Sprawdź liveness
bash
```
curl http://localhost:8080/healthz
```

Sprawdź stan backendów

bash

curl -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:8080/admin/backends

Sprawdź metryki błędów

bash

curl -s http://localhost:8080/metrics | grep -E "backend_errors|backend_healthy|circuit"

Znajdź request po ID
Każdy błąd ma request_id — ten sam ID jest w logach:
bash
```
docker logs proxy 2>&1 | grep 9f2c1a77b3e4d5a6
```

Scenariusz: lawina 503#

text

1. GET /admin/backends → wszystkie healthy: false
2. backend_healthchecks_total{result="failure"} rośnie
3. Sprawdź, czy backendy odpowiadają na /health bezpośrednio
4. Jeśli tak — sprawdź sieć między proxy a backendami
5. Jeśli nie — problem jest w backendach, nie w proxy

Scenariusz: klienci z jednego IP#

Jeśli wszyscy klienci mają IP load balancera, rate limiting działa na pośredniku, nie na klientach:

yaml

rate_limit:
  trusted_proxies:
    - 10.0.0.0/8

Po zmianie zrestartuj proxy i sprawdź client_ip w logach.

Scenariusz: Redis padł#

text

rate_limit_errors_total rośnie
rate_limit_rejected_total stoi

To fail-open — ruch płynie bez limitów. Napraw Redis, a limity wrócą automatycznie. Jeśli potrzebujesz twardego limitu, alertuj na rate_limit_errors_total.

Scenariusz: breaker nie zamyka się#

text

backend_circuit_breaker_open == 1 od dłuższego czasu

Sprawdź half_open_probes — może wymagać więcej sukcesów.
Sprawdź, czy backend naprawdę odpowiada (probe idzie na health_check.path).
Sprawdź open_timeout — breaker czeka przed kolejną próbą.

Logi w JSON#

bash

docker logs proxy 2>&1 | jq 'select(.level == "ERROR")'

bash

docker logs proxy 2>&1 | jq 'select(.status >= 500) | {request_id, path, backend, status}'