CONTRAT CIBLE · VERSION 1.1

Protocole d’observabilité AGP

Une identité, un contrat de santé et un transport OpenTelemetry communs à tous les services, quel que soit leur langage ou leur génération.

Identité de ressource

Attribut obligatoire	Exemple
`service.name`	agenceplus-advertisor
`service.namespace`	agenceplus
`service.version`	1.4.2
`service.instance.id`	instance ou conteneur
`deployment.environment.name`	development, demo, production
`agp.observability.protocol.version`	1.0

Contrat de santé

Chaque base de service expose trois GET anonymes : /health/live, /health/ready et /health. La liveness ne dépend pas d’un système distant ; la readiness vérifie seulement les dépendances indispensables au trafic.

{
  "status": "healthy",
  "service": "agenceplus-advertisor",
  "version": "1.4.2",
  "ready": true,
  "utc": "2026-08-03T14:00:00Z",
  "checks": [{ "name": "cassandra", "status": "healthy", "durationMs": 8.2 }]
}

État de déploiement

La santé décrit la version qui sert le trafic, pas la dernière candidate. Pour tout service livré automatiquement, le déployeur publie donc un état persistant hors de la release active, de préférence sous /deployment/status. L’inventaire distingue explicitement ProtocolVersion 1.0 et 1.1. AgpObserver compare la version cible, la version déclarée active et celle observée par la sonde de santé.

{
  "status": "failed",
  "service": "agenceplus-advertisor",
  "environment": "production",
  "activeVersion": "1.4.2",
  "targetVersion": "1.5.0",
  "startedUtc": "2026-10-01T10:42:00Z",
  "updatedUtc": "2026-10-01T10:44:31Z",
  "completedUtc": "2026-10-01T10:44:31Z",
  "errorCode": "readiness_failed"
}

Les phases sont pending, building, testing, activating, succeeded, failed et rolled_back. Le dernier état terminal reste publié hors de la release active jusqu’à la tentative suivante : une ancienne version saine ne masque donc plus un échec.

Traces et propagation

Propagation W3C traceparent et tracestate sur toutes les frontières HTTP.
Contexte persisté avec les messages et tâches asynchrones.
Noms de spans métier sous la forme domaine.ressource.action.
100 % des traces en développement, échantillonnage parent-based à 10 % par défaut en production.

Métriques et logs

Les métriques déclarent une unité et n’utilisent que des dimensions bornées. Aucun identifiant d’agence, utilisateur, annonce, contact, requête ou fichier ne devient un label. Les logs portent event.name, une catégorie, un niveau et un état d’expurgation. Ils sont corrélés par trace_id/span_id, distingués si nécessaire par agp.logical_service et expurgés des jetons, secrets, cookies, identifiants, coordonnées, IP, URL, chemins, payloads et exceptions brutes. Les identifiants de trace restent des métadonnées structurées et ne sont pas indexés comme labels.

Transport

OTEL_SERVICE_NAME=agenceplus-advertisor
OTEL_RESOURCE_ATTRIBUTES=service.namespace=agenceplus,service.version=1.4.2,deployment.environment.name=demo,agp.observability.protocol.version=1.1
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

Le document normatif complet et le plan d’adoption se trouvent dans le dossier docs/ du dépôt.

← Retour au portail