Obserwowalność i monitorowanie

Obserwowalność na platformie DataFlow AI Platform obejmuje dwie warstwy: warstwę infrastruktury (Prometheus zbierający dane z endpointów Actuatora, wizualizowane w Grafanie) oraz warstwę aplikacji (monitor-service, pełnoprawna funkcja produktu, która śledzi alerty, SLA, koszty, świeżość danych i historię uruchomień pipeline'ów). Ta strona wyjaśnia obie warstwy oraz to, jak ich używać, aby utrzymać pipeline'y w dobrej kondycji.

Stos obserwowalności

  ┌──────────────┐  ┌───────────────┐  ┌──────────────┐  ┌─────────────┐
  │ api-gateway   │  │ metadata-svc  │  │ pipeline-eng  │  │ monitor-svc │
  │ /actuator/    │  │ /actuator/    │  │ /actuator/    │  │ /actuator/  │
  │  prometheus   │  │  prometheus   │  │  prometheus   │  │  prometheus │
  └──────┬───────┘  └──────┬────────┘  └──────┬───────┘  └──────┬──────┘
         │                 │                  │                 │
         └─────────────────┴────────┬─────────┴─────────────────┘
                                    │  scrape every 15s
                          ┌─────────▼──────────┐
                          │   Prometheus       │
                          │   v2.54.1           │
                          └─────────┬──────────┘
                                    │  datasource (default)
                          ┌─────────▼──────────┐
                          │   Grafana 11.2.2   │
                          │   dashboards (UI)  │
                          └────────────────────┘

  monitor-service ── OpenTelemetry tracing + Prometheus metrics + SSE streams
  copilot         ── exposes /metrics (Python)

Stos składa się z trzech współpracujących części:

• Prometheus zbiera metryki z endpointu Spring Boot Actuator każdej usługi.
• Grafana odpytuje Prometheusa jako źródło danych i renderuje dashboardy.
• monitor-service to własna usługa monitorowania produktu — dodaje śledzenie OpenTelemetry, alertowanie na poziomie biznesowym, śledzenie tempa wypalania budżetu SLA (SLA burn-rate) oraz strumienie na żywo SSE, które konsumuje frontend.

Prometheus

Prometheus (prom/prometheus:v2.54.1) jest konfigurowany przez docker/prometheus/prometheus.yml z 15-sekundowym interwałem zbierania danych. Zbiera dane z endpointu /actuator/prometheus z:

• api-gateway
• metadata-service
• pipeline-engine
• pushdown-sql
• lineage-service
• monitor-service

Jakie metryki są udostępniane

Spring Boot Actuator z Micrometerem udostępnia standardowe rodziny metryk JVM i HTTP na /actuator/prometheus, w tym:

Usługa copilot w Pythonie udostępnia własny endpoint /metrics do zbierania danych.

Grafana

Grafana (grafana/grafana:11.2.2) jest provisionowana przez docker/grafana/datasources.yml z pojedynczym źródłem danych Prometheus (http://prometheus:9090), ustawionym jako domyślne.

Na VPS Grafana jest opublikowana na porcie 4001 (przesuniętym, aby współistnieć ze stosem itsm). W domyślnym wdrożeniu Compose działa na porcie 3001.

Zalecane panele dashboardu

Ponieważ dashboardy buduje się ręcznie, przydatny zestaw startowy obejmuje:

• Kondycja żądań — częstotliwość http_server_requests, latencja p50/p95/p99 oraz współczynnik 5xx na usługę.
• Kondycja JVM — trend zużycia sterty, czas pauz GC, liczba wątków.
• Baza danych — aktywne/bezczynne/oczekujące połączenia HikariCP.
• Przepustowość pipeline'ów — liczby uruchomień pipeline'ów i współczynnik awarii (na podstawie danych z monitor-service).

Śledzenie OpenTelemetry

monitor-service realizuje rozproszone śledzenie platformy za pomocą swojej konfiguracji OpenTelemetryConfig oraz filter/TracingFilter. Korelacja żądań jest propagowana od początku do końca za pomocą nagłówka X-Request-Id, dzięki czemu pojedyncze żądanie można śledzić przez gateway i usługi w dół łańcucha.

RequestLoggingFilter gateway'a produkuje strukturalne logi dostępu, a identyfikator żądania wygenerowany lub zaakceptowany na brzegu sieci przepływa przez każdy przeskok. Badając wolne lub nieudane żądanie, przechwyć X-Request-Id z odpowiedzi i użyj go do skorelowania logów i śladów.

Sondy stanu (health) i gotowości (readiness)

api-gateway udostępnia HealthController ze standardowym trio sond Spring Boot Actuator:

Sonda readiness gateway'a jest świadoma zależności — odpytuje endpoint odkrywania OIDC .well-known Keycloaka oraz endpoint stanu metadata-service. Oznacza to, że gateway nie zgłosi gotowości, dopóki jego krytyczne usługi nadrzędne nie będą osiągalne.

Każdy kontener usługi Kotlina definiuje też healthcheck Dockera na /actuator/health. Compose depends_on … condition: service_healthy wykorzystuje je do wymuszenia kolejności startu: postgres → keycloak / kafka / redis → usługi aplikacyjne → frontend.

Aby sprawdzić stan ręcznie na VPS:

# gateway aggregate health
curl -sf http://127.0.0.1:8085/actuator/health | jq

# readiness specifically
curl -sf http://127.0.0.1:8085/actuator/health/readiness | jq

# container health at a glance
docker compose ps

Monitorowanie na poziomie aplikacji — monitor-service

monitor-service to nie tylko instalacja infrastrukturalna — to pełnoprawna funkcja produktu. Odpowiada za alerty, śledzenie SLA, historię uruchomień pipeline'ów, śledzenie kosztów, świeżość danych oraz monitorowanie zmian schematu.

Jego schemat Flyway obejmuje 25 migracji (V9–V25), pokrywających:

• Trwałe przechowywanie alertów i kierowanie powiadomień
• Historię metryk klastra
• Śledzenie tempa wypalania budżetu SLA (SLA burn-rate)
• Kwarantannę danych
• Monitorowanie zmian schematu (tabele monitor_*, w tym monitor_alerts i monitor_pipeline_runs)

monitor-service pobiera również metryki użytkowników Keycloaka, gdy MONITOR_KEYCLOAK_ENABLED=true.

Jak obserwować kondycję pipeline'ów

Uruchomienie pipeline'u przepływa przez platformę i pojawia się w monitorowaniu w kilku punktach:

1. pipeline-engine wykonuje uruchomienie i publikuje zdarzenia uruchomienia przez ExecutionEventPublisher / PipelineRunLogPublisher.
2. Przy awarii zadania SelfHealingService klasyfikuje awarię i stosuje strategie odzyskiwania — te zdarzenia odzyskiwania są obserwowalne.
3. Po zakończeniu monitor-service przyjmuje metryki uruchomienia i ocenia koszt, SLA oraz świeżość, podnosząc alerty tam, gdzie przekroczono progi.
4. Historia uruchomień jest trwale przechowywana w monitor_pipeline_runs; alerty w monitor_alerts.

Aby sprawdzić stan uruchomień pipeline'ów bezpośrednio w bazie danych:

docker compose exec postgres psql -U postgres -d dataflow_metadata \
  -c "SELECT status, COUNT(*) FROM monitor_pipeline_runs GROUP BY status;"

Strumienie na żywo SSE

Platforma wypycha dane obserwowalności w czasie rzeczywistym do interfejsu użytkownika za pomocą Server-Sent Events zamiast odpytywania (polling).

Dodatkowo WebSocket przenosi strumieniowanie logów uruchomień pipeline'ów na /api/v1/runs/{runId}/stream — gateway przepisuje http→ws do pipeline-engine, a komponent LogStream frontendu renderuje aktualizacje stanu zadań i logów na żywo.

SSEManager frontendu (EventSource) napędza alerty, metryki i powiadomienia; interceptor żądań w frontend/src/api/client.ts zapewnia, że żaden strumień nie otworzy się przed gotowością tokenu Keycloaka.

Logowanie

Każda usługa produkuje logi strukturalne. RequestLoggingFilter gateway'a emituje strukturalne logi dostępu na brzegu sieci, a nagłówek korelacji X-Request-Id przewija się przez usługi w dół łańcucha, dzięki czemu żądanie można zrekonstruować przez wiele przeskoków.

Na VPS logi kontenerów są dostępne przez Docker Compose:

# tail logs for one service
docker compose logs -f --tail=200 api-gateway

# logs since a timestamp
docker compose logs --since 2026-05-20T04:00:00 monitor-service

Diagnozując problem, przechwyć X-Request-Id z nieudanej odpowiedzi i wyszukaj go (grep) w logach odpowiednich usług, aby prześledzić pełną ścieżkę żądania.

Alertowanie

Alertowanie istnieje na dwóch poziomach.

Alertowanie na poziomie aplikacji (monitor-service)

monitor-service ocenia warunki tempa wypalania budżetu SLA, kosztu, świeżości oraz zmian schematu i trwale zapisuje alerty do monitor_alerts, z konfigurowalnym kierowaniem powiadomień. Alerty te są prezentowane na żywo w interfejsie użytkownika przez strumień alertów SSE oraz przez skrzynkę odbiorczą powiadomień.

Alertowanie infrastruktury (ścieżka GKE)

Runbook DR oraz produkcyjny workflow GitHub Actions odwołują się do PagerDuty (klucze kierujące P1/P2) oraz Slacka (#dataflow-incidents, SLACK_WEBHOOK_DEPLOYMENTS). Polityki alertów Cloud Monitoring są opisane w docs/deployment-scenarios.html.

Szybka lista kontrolna obserwowalności

Gdy potrzebujesz wiedzieć „czy platforma jest teraz w dobrej kondycji?", przejdź przez tę listę:

1. docker compose ps — czy wszystkie 8 usług oraz warstwa infrastruktury są healthy?
2. curl -sf http://127.0.0.1:8085/actuator/health/readiness — czy gateway jest gotowy?
3. Otwórz Grafanę — czy latencja żądań p99 i współczynnik 5xx mieszczą się w normalnych granicach?
4. Sprawdź monitor_pipeline_runs pod kątem skoku statusu FAILED.
5. Sprawdź monitor_alerts (oraz strumień alertów w interfejsie) pod kątem niepotwierdzonych alertów.
6. docker compose logs --since 1h na dowolnej usłudze wykazującej błędy — koreluj po X-Request-Id.