Aller au contenu

Story OP-020: Backend observabilité (Micrometer + health endpoint + MDC)

Module: operator-console Slice: Architecture §11 OP-005 + §10 Side: [BACKEND] Version target: V0.1.0 Priority: 21 (dernière story V0) Depends on: OP-003 (campagne send pour metric), OP-004 (recovery) Can develop concurrently with: aucune (story horizontale) Merge order: After V0.0.3 (toute la stack feature stable) Estimated complexity: S PRD User Stories: V0.1.0 envelope (hooks observabilité ARTCI + ops) Wireframe: N/A — backend only

Objective

Compléter les hooks d'observabilité de l'arch §10 : métriques Micrometer formalisées, endpoint health dédié OP, enrichissement MDC structuré sur tous les logs OP. Préparation V1 alerting + Datadog.

Backend Scope

Service Layer

  • OperatorMetrics : @Component qui enregistre 7 métriques (extension de l'arch §10.1) :
  • op_campaigns_created_total (Counter) — incrémenté dans CampaignService.createDraft.
  • op_campaigns_sent_total (Counter) — dans CampaignSenderService.send post-TX0.
  • op_campaign_contracts_status (Gauge, per-status) — scan périodique 60 s.
  • op_api_request_duration (Timer) — auto via @Timed sur les controllers OP.
  • op_notif_dispatch_latency (Histogram) — entre publish event et UPDATE cc dans le worker.
  • op_link_creation_latency (Histogram) — duration de SignedLinkService.createLink côté OP.

  • op_dispatch_recovery_lag (Gauge) — déjà émis par OP-004, intégré ici.

  • OperatorHealthIndicator : HealthIndicator qui assemble :

  • Postgres connectivity (SELECT 1 sur datasource tenant + platform).
  • Keycloak token validation (decode token signing key).
  • NOTIF client availability (ping via NotificationDispatchService.healthCheck()).
  • TENANT cache age (≤ TTL).

  • Status OUT_OF_SERVICE si une de ces dépendances échoue.

  • OperatorHealthController :

  • GET /api/operator/health/ready (RBAC : PLATFORM_ADMIN + monitoring service account).

  • GET /api/operator/health/live (no-auth simple liveness).

  • OperatorMdcEnricher : HandlerInterceptor qui ajoute MDC keys tenant_id, agency_id, user_id, role, correlation_id, endpoint à chaque requête. Cleanup post-request.

  • OperatorLoggingConfiguration : logback logback.xml (étendu — pas refait) intègre les MDC keys dans le JSON layout existant.

API Endpoints

Method Path Request Response Auth
GET /api/operator/health/ready — { status, details: {db, keycloak, notif, tenantCache} } PLATFORM_ADMIN / monitoring
GET /api/operator/health/live — { status: "UP" } (200) no-auth

Validation Rules

N/A.

Multi-Tenant Considerations

  • Métriques par tenant : étiquette tenant_id sur les counters/gauges/histograms (haute cardinalité — borné à 1000 tenants en V1).
  • Health endpoint n'expose pas de données tenant-spécifiques.

Audit & Logging

  • MDC enrichi systématiquement sur tous les logs OP.
  • Logs structurés JSON (ELK-compatible).
  • Émission Prometheus (local) + CloudWatch (staging/prod) — config existante TENANT S0.

Acceptance Criteria

AC-001: Métriques émises sur création + envoi + worker
Given un opérateur crée puis envoie une campagne 5 contrats
When je requête /actuator/prometheus
Then op_campaigns_created_total a incrémenté de 1
And op_campaigns_sent_total a incrémenté de 1
And op_notif_dispatch_latency a 5 observations
And op_link_creation_latency a 5 observations.

AC-002: Health endpoint répond UP avec toutes les deps OK
Given Postgres + Keycloak + NOTIF mock OK
When GET /api/operator/health/ready avec token PLATFORM_ADMIN
Then 200 { status: "UP", details: { db: "UP", keycloak: "UP", notif: "UP", tenantCache: "UP" } }.

AC-003: Health endpoint DOWN si NOTIF down
Given NOTIF mock rejette
When GET /health/ready
Then 503 { status: "OUT_OF_SERVICE", details: { notif: "DOWN", ... } }.

AC-004: MDC enrichi sur tous les logs
Given une requête authentifiée
When un controller log un INFO
Then le log JSON contient les 6 MDC keys (tenant_id, agency_id, user_id, role, correlation_id, endpoint).

Compliance Rules

  • PRD V0 §4 ligne OP V0.1.0 : observabilité ARTCI + ops. VÉRIFIÉ.
  • ARTCI traçabilité : MDC user_id + tenant_id sur tous les logs. VÉRIFIÉ.

Standards & Conventions

  • docs/standards/java-spring-guidelines.md — Micrometer + Actuator.

Testing Requirements

Unit Tests

  • OperatorMetricsTest : chaque metric émis sur le bon trigger.
  • OperatorMdcEnricherTest : cleanup post-request (pas de leak).

Integration Tests

  • HealthEndpointIT AC-002 + AC-003.
  • MetricsExpositionIT : vérifie endpoint Prometheus contient les 7 metrics.

What QA Will Validate

  • Curl /actuator/prometheus → métriques OP visibles.
  • Logs JSON dans CloudWatch staging contiennent les MDC keys.

Out of Scope

  • Alerting CloudWatch (Datadog rules) → infra ops, hors story dev.
  • Distributed tracing OpenTelemetry → V1.
  • Métriques frontend (Sentry / RUM) → V1.

Definition of Done

  • [ ] 7 métriques Micrometer émises et exposées sur /actuator/prometheus
  • [ ] /health/ready + /health/live opérationnels
  • [ ] AC-001..AC-004 passent
  • [ ] MDC propagé sur tous les logs OP
  • [ ] Documentation .env.example mise à jour (variables Actuator)
  • [ ] Tests intégration verts