Supervision

Le point de terminaison de santé : GET /api/health répond 200 quand Ronne peut servir, avec chaque contrôle :

{"status":"ok","checks":{"database":"ok","storage":"ok"}}

et 503 quand il ne peut pas, sous la forme d'erreur de l'API : setup_required avant l'installation, database_unavailable quand la base ne répond pas en 3 secondes, storage_unavailable quand le dossier de stockage n'accepte pas d'écriture (son details.checks dit lequel). Le contrôle de santé de Docker, les services et les scripts d'installation l'attendent, et un répartiteur de charge peut aussi le faire. Il ne dit rien d'autre (ni version, ni chemin, ni durée) : il est public. La raison d'un échec est dans le journal (db.unavailable, storage.unavailable).

Les métriques et les traces vont à un collecteur OpenTelemetry que vous exploitez, en OTLP/HTTP. Elles sont désactivées tant que vous n'avez pas réglé son adresse : alors, et seulement alors, Ronne charge OpenTelemetry. Réglez-la dans le fichier de réglages ou l'environnement (avec Docker, dans le fichier .env à côté de compose.yaml, puis docker compose up -d), puis redémarrez Ronne :

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20…   # facultatif, celui du collecteur
OTEL_SERVICE_NAME=ronne-marketplace                  # facultatif; c'est la valeur par défaut
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

Les variables OTEL_* standard d'OpenTelemetry fonctionnent comme il les documente : le point de terminaison propre à un signal (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, …_METRICS_ENDPOINT), l'échantillonneur (OTEL_TRACES_SAMPLER), l'intervalle d'export (OTEL_METRIC_EXPORT_INTERVAL, 60 s par défaut), et OTEL_EXPORTER_OTLP_PROTOCOL=http/json pour envoyer les traces en JSON au lieu de protobuf (les métriques partent toujours en JSON). OTEL_SDK_DISABLED=true désactive la télémétrie même si une adresse est réglée. Le NEXT_OTEL_VERBOSE de Next.js lui-même est désactivé : ses spans en plus porteraient les chemins avec leurs valeurs réelles, noms privés compris. Un collecteur arrêté ou lent ne ralentit jamais une requête : les exports sont retentés en arrière-plan puis abandonnés, avec au plus une ligne telemetry.export_failed par minute.

Un collecteur qui les reçoit, garde les traces dans son propre journal et offre les métriques à Prometheus sur :8889/metrics (otel-collector.yaml) :

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch: {}
exporters:
  # Métriques à collecter par Prometheus, sur http://<collecteur>:8889/metrics.
  prometheus:
    endpoint: 0.0.0.0:8889
  # Traces dans le journal du collecteur : remplacez par l'exportateur de votre outil de traces.
  debug:
    verbosity: basic
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

docker run -p 4318:4318 -p 8889:8889 \
  -v ./otel-collector.yaml:/etc/otelcol-contrib/config.yaml:ro \
  ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.162.0

Les métriques, chacune avec ces seuls attributs :

Les traces : les spans de Next.js lui-même pour chaque requête, nommés par le motif de la route; un span par requête à la base, avec son SQL et ses marqueurs, jamais les valeurs; storage.put et storage.get avec leur nombre d'octets; et ronne.release, ronne.feed.build et ronne.draft.upload. Le span d'une route de l'API porte ronne.request_id, le X-Request-Id de sa réponse.

Jamais envoyé : les identifiants d'utilisateurs, les courriels, les adresses IP des personnes, les agents utilisateurs, les jetons, les valeurs d'une requête à la base, ni les noms des éléments, des portées et des espaces de travail. Le chemin et l'URL d'une requête ne sont pas envoyés (le chemin de la page d'un élément le nomme), ni le message d'une erreur. Les spans ne portent que les attributs que Ronne liste; tout autre ajouté par une bibliothèque est écarté. Chaque requête est sa propre trace : le traceparent, le tracestate et le baggage de l'appelant sont ignorés, donc une trace ne rejoint jamais celle d'un proxy ou d'un client. La ressource dit service.name, service.version, deployment.* et ce que vous réglez dans OTEL_RESOURCE_ATTRIBUTES. Rien ne va ailleurs qu'à votre collecteur.

Alertes utiles : le contrôle de santé en échec (ronne.health à 0, ou le 503 du point de terminaison de santé); une hausse des réponses 5xx (http.server.request.duration par http.response.status_code); une hausse des connexions échouées ou limitées (ronne.sign_ins, ronne.rate_limited); des requêtes lentes à la base (ronne.db.query.duration).

Journaux et traces ensemble : avec le traçage actif, chaque ligne de journal écrite pendant une requête porte traceId et spanId (Journaux), une ligne mène donc à sa trace, et le ronne.request_id d'une trace aux lignes.