Stack technique¶

Backend¶

Composant	Technologie	Version
Framework	Spring Boot	3.x
Langage	Java	17
BDD	MySQL	8.0
Migrations	Flyway	(inclus Spring Boot)
Pool BDD	HikariCP	(inclus Spring Boot)
Serveur HTTP	Tomcat (embarqué)	(inclus Spring Boot)
Métriques	Micrometer + Actuator	(inclus Spring Boot)
Build	Maven	3.x

Endpoints Actuator exposés¶

management.endpoints.web.exposure.include: health,info,metrics,prometheus
management.endpoint.health.show-details: always

Endpoint	URL	Usage
Métriques Prometheus	`/actuator/prometheus`	Scraped par Prometheus
Santé	`/actuator/health`	Healthcheck Docker
Heap dump	`/actuator/heapdump`	Analyse mémoire JVM

Configuration CORS¶

Le CORS est géré par CorsConfig.java via la variable d'environnement CORS_ALLOWED_ORIGINS. En local les origines autorisées sont http://localhost:9091,http://localhost:3003,http://localhost:3004. En production, elles sont définies dans .env.production.

Frontend¶

Composant	Technologie
Framework	React 18
Build tool	Vite
Serveur	Nginx (Alpine)
Chaos agent	Vanilla JS (chaos-agent.js)
Web Worker	API native navigateur

Injection d'URLs au démarrage¶

Le script env-inject.sh substitue les URLs dans le bundle JS au démarrage du container. Les fichiers .sh doivent avoir des fins de ligne LF (géré par .gitattributes).

Monitoring¶

Composant	Technologie
Serveur	Node.js + Express
Métriques Docker	Docker socket (`/var/run/docker.sock`)
Format métriques	Prometheus text format 0.0.4
Métriques navigateur	POST JSON → exposées dans `/metrics`

Observabilité¶

Outil	Rôle
Prometheus	Collecte et stockage métriques (rétention 15 jours)
Grafana	Dashboards et visualisation
Monitoring HTML	Dashboard temps réel sans dépendance externe
Loki + Promtail	Agrégation et recherche de logs containers
Tempo 2.4.2	Stockage traces distribuées OpenTelemetry
Pyroscope 1.18.1	Continuous profiling (flamegraphs CPU Java)

APM — Agents injectés dans le backend¶

Deux agents Java injectés via JAVA_OPTS au démarrage du container perfshop-app :

Agent	Version	Rôle	Destination
OpenTelemetry Java Agent	1.33.6	Traces HTTP + SQL + méthodes	Tempo (OTLP gRPC port 4317)
Pyroscope Java Agent	0.14.0	Flamegraphs CPU continus	Pyroscope (HTTP port 4040)

Les agents sont téléchargés au moment du build Docker (Dockerfile.synology) — aucune dépendance Maven ajoutée.

# extrait docker-compose.yml (prod NAS + build VPS)
environment:
  JAVA_OPTS: >
    -javaagent:/app/agents/opentelemetry-javaagent.jar
    -Dotel.service.name=perfshop
    -Dotel.exporter.otlp.endpoint=http://perfshop-tempo:4317
    -Dotel.instrumentation.http.capture-headers.server.request=X-Admin-Token,Content-Type
    -Dotel.instrumentation.jdbc.captured-statements.enabled=true
    -Dotel.span.attribute.count.limit=256
    -javaagent:/app/agents/pyroscope-agent.jar
    -Dpyroscope.server.address=http://perfshop-pyroscope:4040
    -Dpyroscope.profiler.event=cpu
    -Dpyroscope.profiler.alloc=512k
    -Dpyroscope.profiler.lock=10ms
    -Dpyroscope.profilingInterval=PT0.02S

docker-compose.desktop.yml — mode itimer

Identique au-dessus sauf -Dpyroscope.profiler.event=itimer. perf_event_open est bloqué sous Docker Desktop ; itimer utilise SIGPROF (100% JVM).

Propriété OTel	Effet
`capture-headers.server.request`	Header `X-Admin-Token` visible dans les spans Tempo
`jdbc.captured-statements=true`	Requête SQL (`db.statement`) visible dans les spans
`span.attribute.count.limit=256`	Évite la troncature sur les spans chaos riches (A8, A9)

Propriété Pyroscope	Effet
`profiler.alloc=512k`	Active le flamegraph mémoire (heap) — panel Grafana F3-OOM
`profiler.lock=10ms`	Active le flamegraph de contention verrou — panel A8 race condition
`profilingInterval=PT0.02S`	50 Hz au lieu de 100 Hz — overhead CPU réduit (~1-2%)

Compatibilité Tempo

Tempo 2.4.2 est la version stable utilisée. Les versions 2.7+ introduisent une architecture distribuée (live-store) incompatible avec le mode single-binary sans Kafka. Le dashboard APM utilise queryType: "traceql" (API v1 /api/search) compatible 2.4.2 — et type: "table" pour le panel Traces (le plugin natif traces de Grafana 12 requiert l'API v2 absente de Tempo 2.4.2).

Ports locaux (Docker Desktop Windows/Mac/Linux)¶

Service	Port local
Frontend	http://localhost:9091
Backend API	http://localhost:9080
Monitoring	http://localhost:3001
Grafana	http://localhost:3002
Chaos Admin	http://localhost:3003
Admin	http://localhost:3004
Documentation	http://localhost:9085
Prometheus	http://localhost:9092