Aller au contenu

Seaway — Observability Overview

Cette documentation présente les principes d'architecture et les pratiques d'ingénierie du projet.

Les détails opérationnels et configurations d'infrastructure internes sont intentionnellement omis.

Objectif

Mettre en place une stack d'observabilité production-ready pour l'application Seaway.

Objectifs :

  • exposer des métriques techniques et applicatives
  • isoler le plan d'observabilité du plan API publique
  • permettre une visualisation en temps réel
  • versionner la configuration dans le dépôt

Stack

  • Spring Boot Actuator + Micrometer
  • Prometheus v2.51.0
  • Grafana 10.4.0

Architecture

flowchart LR

    Backend["Backend :8080 (API)"]
    Actuator["Actuator :8081 (métriques)"]
    Prometheus["Prometheus"]
    Grafana["Grafana"]

    Backend --- Actuator
    Prometheus -->|scrape| Actuator
    Grafana -->|query| Prometheus

Deux ports distincts sont exposés par le backend :

  • :8080 — API publique, exposée via Nginx
  • :8081 — Actuator, jamais exposé publiquement

Cette séparation garantit que les métriques ne transitent jamais par le reverse proxy.

Isolation du port Actuator

L'endpoint /actuator/prometheus est exposé sur un port de management dédié (:8081).

Configuration Spring Boot :

management:
  server:
    port: 8081

Nginx ne route aucun trafic vers ce port.

Prometheus atteint le backend directement via le réseau Docker interne, sans passer par le reverse proxy.

Spring Security

Une SecurityFilterChain dédiée (@Order(1)) autorise les requêtes actuator sans JWT.

Principes :

  • les endpoints actuator ne nécessitent pas d'authentification
  • la chaîne dédiée est prioritaire sur la chaîne principale
  • le port :8081 n'est pas accessible publiquement

Séparation dev / prod

Deux configurations Prometheus distinctes sont versionnées :

prometheus.dev.yml

  • Prometheus (conteneur Docker) scrape host.docker.internal:8081
  • permet de collecter les métriques d'un backend lancé localement (JetBrains)

prometheus.prod.yml

  • Prometheus scrape backend:8081
  • communication via le réseau Docker interne

Métriques disponibles

JVM

  • heap utilisé / disponible
  • garbage collection (durée, fréquence)
  • threads actifs
  • classes chargées

Base de données

HikariCP :

  • connexions actives
  • connexions idle
  • connexions en attente
  • temps d'acquisition

Kafka

  • métriques producer (latence, taux d'envoi)
  • métriques consumer (lag, taux de traitement)
  • métriques listener

HTTP

  • nombre de requêtes par endpoint
  • temps de réponse (percentiles)
  • métriques Spring Security

Système

  • CPU
  • mémoire système
  • uptime

Logs

  • Logback : events par niveau (INFO, WARN, ERROR)

Grafana

Grafana 10.4.0 est configuré avec un provisioning automatique.

Au démarrage, Grafana charge automatiquement :

  • la datasource Prometheus
  • le dashboard applicatif

Le dashboard est versionné en JSON dans le dépôt.

Compatibilité :

  • dashboard sélectionné sans plugins Angular
  • compatible nativement avec Grafana 10+

Principes clés

  • port Actuator isolé, jamais exposé via Nginx
  • configuration Prometheus versionnée par environnement
  • dashboard Grafana versionné dans le dépôt
  • provisioning automatique au démarrage
  • aucune dépendance Angular (compatibilité Grafana 10+)