Observabilité et corrélation des paiements (Observabilite Et Correlation Des Paiements)

Dans la section précédente, nous avons vu comment le webhook et le chemin synchrone rivalisent avec le même enregistrement et comment le jeton de version et le bail résolvent ce problème. Alors, comment voyez-vous cela lorsqu'une course a lieu ou qu'un paiement est bloqué dans FinalizePending pendant des heures ?

Dans un système de paiement distribué, il ne suffit pas de dire « quelque chose s'est mal passé » ; Il faut répondre en quelques secondes à la question de savoir quel identifiant de paiement, à quelle étape et avec quelles preuves il a été bloqué. L'observabilité n'est pas un luxe ici : c'est l'infrastructure qui détermine ce que l'agent de réconciliation analysera et quel runbook l'ingénieur de garde ouvrira.```text Payment #8812 ├─ trace: checkout-orchestrator ├─ step log: ChargeSent → WebhookReceived → FinalizeAttempted └─ metric: deferred_finalize_age_seconds = 847

## Concepts à la première mention```text
📦 Payment ID (Correlation Spine)
Tüm servisler, loglar ve metriklerde tekrarlanan, ödeme yaşam döngüsünün birincil anahtarı.

📦 Step Event Log
Bir ödemenin her anlamlı adımını kaydeden, append-only olay dizisi.

📦 Deferred Finalize
Ödeme PSP tarafında sonuçlanmış olabilir ama local sistem henüz terminal statüye geçmemiştir.

📦 Structured Log
Serbest metin yerine alan tabanlı, sorgulanabilir log kaydı.
```L’identifiant de demande ou l’identifiant de trace est temporaire ; L’identifiant de paiement est permanent. Lorsque vous recevez une réclamation client, ce que vous recherchez est l’identifiant de paiement, pas l’identifiant de demande.

## Identifiant de paiement : colonne vertébrale de la corrélation

Lorsque l'orchestrateur de paiement initie un paiement, l'identifiant de paiement est généré et transmis à chaque service à partir de ce moment : dans la demande de facturation adressée à la passerelle du fournisseur, dans les métadonnées du webhook, dans le journal des événements d'étape, dans les balises de métrique. Cet identifiant relie des traces éparses à une seule histoire.```text
❌ Korelasyonsuz
  [ERROR] webhook processing failed
  [ERROR] charge timeout in gateway
  → hangi ödeme?

✓ Payment id ile
  paymentId=8812 step=WebhookReceived error=version_conflict
  paymentId=8812 step=ChargeSent latency_ms=4200
  → aynı ödeme, farklı adımlar, anında görünür
```Les étendues de trace doivent également porter un identifiant de paiement. Lorsque vous entrez une trace, vous devriez voir toutes les étapes depuis le paiement jusqu'à la finalisation du webhook — même si l'identifiant de la demande change entre les différents services, l'identifiant de paiement reste constant.

## Journal des événements d'étape : calendrier de paiement

Les métriques répondent à la question « combien » ; étape du journal des événements à la question « que s'est-il passé, dans l'ordre ». Chaque étape significative produit un enregistrement :```text
8812  ChargeRequested      orchestrator   amount=249.00
8812  ChargeSent           gateway        providerRef=ch_abc
8812  SyncResponsePending  orchestrator   redirectUrl=issued
8812  WebhookReceived      gateway        event=PaymentCaptured
8812  FinalizeAttempted    orchestrator   version=3→4
8812  FinalizeSucceeded    orchestrator   status=Captured
```Il s'agit uniquement d'un ajout de journal ; Une étape n’est pas supprimée, une nouvelle étape est ajoutée. L'intervention de compensation ou de réconciliation écrit également sa propre étape — afin que la réponse à la question « pourquoi ce paiement a-t-il été finalisé deux fois » ne soit pas perdue.

Le journal des événements d'étape ne doit pas être confondu avec la piste d'audit : l'audit répond à la question « qui a fait quoi » ; journal des étapes « qu'est-ce que le système a fait, dans quel ordre ». Les deux se complètent.

## Métriques de finalisation différée : rendre visible la suspension silencieuse

Un paiement avec le statut `FinalizePending` peut avoir déjà été conclu du côté PSP, bien que le résultat n'ait pas encore été montré au client. Cette fenêtre est normale, mais sa durée doit être mesurée.```text
Metrik: deferred_finalize_count
  → şu an FinalizePending'de olan ödeme sayısı

Metrik: deferred_finalize_age_seconds (histogram)
  → her ödemenin bu statüde ne kadar kaldığı

Alert: deferred_finalize_age_p99 > 600s
  → finalize pipeline'ında sistemik sorun
```Ces mesures déterminent également « l'urgence » avec laquelle le travailleur de la réconciliation doit effectuer une analyse. Si `deferred_finalize_age_seconds` augmente, le problème ne vient peut-être pas d'un seul paiement, mais du pipeline de finalisation ou du traitement du webhook.

## Disposition du tableau de bord : visibilité opérationnelle

| Panneau | Spectacles | Déclencheur d'action |
| --- | --- | --- |
| Décompte finalisé différé | Volume de paiement installé | Hausse continue → revue du pipeline |
| Finaliser l'âge P99 | Pire retard | Dépassement SLA → astreinte |
| Écart de journal d'étape | Étape manquante (pas de WebhookReceived) | Problème de livraison du webhook |
| Taux de conflits de versions | Intensité de la course | Réglage de la concurrence |

## Distinctions souvent confuses```text
❌ Request id yeterli korelasyon sağlar
✓ Request id geçicidir; payment id ödeme boyunca kalıcıdır

❌ Log volume = observability
✓ Sorgulanabilir, payment id'li structured log = observability

❌ Metrikler geliştirme için yeterli
✓ Step event log, metriklerin gösteremediği sıra ve bağlamı taşır
```## Journal par rapport au journal des événements d'étape par rapport à l'audit

| Genre | Question | Exemple |
| --- | --- | --- |
| Journal structuré | Détails instantanés de l'événement | WebhookReceived, latence=120ms |
| Journal des événements d'étape | Séquence du cycle de vie | ChargeSent → WebhookReceived → Finaliser |
| Journal d'audit | Intervention humaine/processus | L'opérateur X a déclenché une guérison manuelle |

## Liste de contrôle d'observabilité

1. Chaque ligne de journal, étendue de trace et étiquette métrique comporte-t-elle un identifiant de paiement ?
2. Le journal des événements d'étape est-il uniquement en annexe et inclut-il chaque étape significative ?
3. Les métriques `deferred_finalize_count` et `deferred_finalize_age_seconds` sont-elles définies ?
4. Existe-t-il une alerte basée sur SLA pour Finalize age P99 ?
5. Est-il possible de retracer le chemin complet depuis le journal des étapes, depuis la caisse jusqu'au statut du terminal, avec un identifiant de paiement ?
6. Les enregistrements corrigés par le travailleur de rapprochement sont-ils consignés dans le journal des étapes ?

## Ce qu'il faut retenir de cet article

1. L’identifiant de paiement est l’épine dorsale de toute observabilité ; La demande d’identification seule ne suffit pas.
2. Le journal des événements d'étape est la chronologie du paiement ; Il porte l'ordre que les métriques ne peuvent pas afficher.
3. Les mesures de finalisation différées rendent les sorties tranquilles mesurées et stimulantes.
4. L’observabilité n’est pas un luxe ; Détermine ce que recherchent le rapprochement et les astreintes.

> Lorsqu'un paiement est bloqué, « regardons les journaux » ne suffit pas ; Vous avez besoin d'un journal des événements d'étape et d'une métrique de finalisation différée qui indiquera à quelle étape vous vous trouvez en quelques secondes avec l'identifiant de paiement.

Dans la section suivante, nous construisons des pipelines de récupération et des runbooks en plus de cette visibilité : l'automatisation d'abord, l'intervention humaine dans le cadre de l'unicité.