支払いの観察可能性と相関性 (Payment Observability And Correlation)

前のセクションでは、Webhook と同期パスが同じレコードに対してどのように競合するのか、またバージョン トークンとリースがこれをどのように解決するのかを見てきました。では、競合が発生したり、支払いが FinalizePending で数時間滞留したりした場合、これをどのように確認すればよいでしょうか?

分散型決済システムでは、「何か問題が発生した」と言うだけでは十分ではありません。どの支払い ID が、どのステップで、どのような証拠によってスタックされたのかという質問には、数秒以内に答える必要があります。ここでは可観測性は贅沢ではありません。調整担当者が何をスキャンするか、オンコール エンジニアがどの Runbook を開くかを決定するのはインフラストラクチャです。```text Payment #8812 ├─ trace: checkout-orchestrator ├─ step log: ChargeSent → WebhookReceived → FinalizeAttempted └─ metric: deferred_finalize_age_seconds = 847

## 最初に説明した概念```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ı.
```リクエスト ID またはトレース ID は一時的なものです。支払い ID は永続的です。顧客から苦情を受け取ったときに必要なのは、リクエスト ID ではなく、支払い ID です。

## 支払い ID: 相関関係のバックボーン

チェックアウト オーケストレーターが支払いを開始すると、支払い ID が生成され、それ以降、プロバイダー ゲートウェイへの請求リクエスト、Webhook メタデータ、ステップ イベント ログ、メトリック タグなど、すべてのサービスに渡されます。このイドは、点在する痕跡を一つの物語へと結びつける。```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
```トレーススパンには支払い ID も含まれている必要があります。トレースを入力すると、チェックアウトから Webhook の完了までのすべてのステップが表示されます。リクエスト ID が異なるサービス間で変化しても、支払い ID は一定のままです。

## ステップイベントログ: 支払いタイムライン

メトリクスは「いくつあるか」という質問に答えます。 「何が起こったのか、順番に」という質問にイベントログをステップします。重要なステップごとにレコードが生成されます。```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
```これはログの追加のみです。ステップは戻されず、新しいステップが追加されます。補償または和解の介入にも独自のステップが記述されているため、「なぜこの支払いが 2 回完了したのか」という質問に対する答えが失われることはありません。

ステップ イベント ログを監査証跡と混同しないでください。監査は「誰が何をしたか」という質問に答えます。ステップログ「システムが何をどの順序で実行したか」。この 2 つは互いに補完し合います。

## 遅延ファイナライズメトリクス: サイレントハングを可視化

ステータス `FinalizePending` の支払いは、PSP 側ですでに完了している可能性がありますが、結果はまだ顧客に表示されていません。この期間は正常ですが、どのくらいの期間続くかを測定する必要があります。```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
```これらのメトリクスは、調整担当者が「どれだけ緊急に」スキャンする必要があるかも決定します。 `deferred_finalize_age_seconds` が上昇している場合、問題は 1 回の支払いではなく、ファイナライズ パイプラインまたは Webhook 処理にある可能性があります。

## ダッシュボードのレイアウト: 操作の可視性

|パネル |ショー |アクショントリガー |
| --- | --- | --- |
|遅延確定カウント |インストール済みの支払い額 |継続的な上昇 → パイプライン見直し |
|年齢を確定する P99 |最悪の遅延 | SLA 超過 → オンコール |
|ステップログギャップ |ステップが欠落しています (WebhookReceived がありません) | Webhook 配信の問題 |
|バージョン競合率 |レースの激しさ |同時実行チューニング |

## 混同されやすい区別```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
```## ログとステップイベントのログと監査

|ジャンル |質問 |例 |
| --- | --- | --- |
|構造化されたログ |インスタントイベントの詳細 | Webhook 受信、レイテンシー = 120ms |
|ステップイベントログ |ライフサイクルシーケンス | ChargeSent → WebhookReceived → Finalize |
|監査ログ |人間/プロセスの介入 |オペレーター X が手動回復をトリガーしました |

## 可観測性チェックリスト

1. 各ログ行、トレース スパン、およびメトリック タグには支払い ID が含まれていますか?
2. ステップ イベント ログは追加専用であり、意味のあるすべてのステップが含まれていますか?
3. `deferred_finalize_count` および `deferred_finalize_age_seconds` メトリクスは定義されていますか?
4. ファイナライズ期間 P99 に関する SLA ベースのアラートはありますか?
5.支払いIDを使用して、チェックアウトから端末ステータスまでのステップログのフルパスを追跡することは可能ですか?
6. 調整担当者によって修正されたレコードはステップ ログに書き込まれますか?

## この記事で覚えておくべきこと

1. 支払い ID はすべての可観測性のバックボーンです。リクエスト ID だけでは十分ではありません。
2. ステップイベントログは支払いのタイムラインです。指標には表示できない順序が含まれます。
3. 遅延ファイナライズメトリクスにより、静かな時間を測定し、刺激的なものにします。
4. 可観測性は贅沢ではありません。調整とオンコールで何を求めるかを決定します。

> 支払いが滞った場合、「ログを見てみましょう」だけでは十分ではありません。ステップ イベント ログと、支払い ID を使用して数秒以内にどのステップにいるかを示す遅延ファイナライズ メトリックが必要です。

次のセクションでは、この可視性に基づいて回復パイプラインとランブックを構築します。まず自動化を行い、独自性の壁の中で人間が介入します。