Observabilidad y correlación de pagos (Observabilidad Y Correlacion DE Pagos)

En la sección anterior, vimos cómo el webhook y la ruta síncrona compiten por el mismo registro y cómo el token de versión y el arrendamiento resuelven esto. Entonces, ¿cómo ves esto cuando ocurre una carrera o un pago se queda atascado en FinalizePending durante horas?

En un sistema de pago distribuido, no basta con decir "algo salió mal"; La pregunta de qué ID de pago, en qué paso y con qué pruebas se bloqueó debe responderse en cuestión de segundos. La observabilidad no es un lujo aquí: es la infraestructura la que determina qué escaneará el trabajador de conciliación y qué runbook abrirá el ingeniero de guardia.```text Payment #8812 ├─ trace: checkout-orchestrator ├─ step log: ChargeSent → WebhookReceived → FinalizeAttempted └─ metric: deferred_finalize_age_seconds = 847

## Conceptos en la primera mención```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ı.
```La identificación de solicitud o la identificación de seguimiento es temporal; La identificación de pago es permanente. Cuando recibe una queja de un cliente, lo que busca es la identificación del pago, no la identificación de la solicitud.

## ID de pago: columna vertebral de la correlación

Cuando el organizador de pago inicia un pago, la identificación del pago se genera y se lleva a cada servicio a partir de ese momento: en la solicitud de cargo a la puerta de enlace del proveedor, en los metadatos del webhook, en el registro de eventos de pasos, en las etiquetas de métricas. Esta identificación conecta rastros dispersos a una sola historia.```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
```Los tramos de seguimiento también deben llevar una identificación de pago. Cuando ingresa un seguimiento, debería ver todos los pasos desde el pago hasta la finalización del webhook; incluso si la identificación de la solicitud cambia entre diferentes servicios, la identificación del pago permanece constante.

## Registro de eventos de pasos: cronograma de pago

Las métricas responden a la pregunta "cuántos"; paso del registro de eventos a la pregunta "qué pasó, en orden". Cada paso significativo produce un registro:```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
```Esto es sólo para agregar registros; No se retrocede un paso, se añade un paso nuevo. La intervención de compensación o reconciliación también tiene su propio paso, de modo que no se pierda la respuesta a la pregunta "¿por qué este pago se realizó dos veces?".

El registro de eventos de pasos no debe confundirse con el registro de auditoría: la auditoría responde a la pregunta "quién hizo qué"; registro de pasos 'qué hizo el sistema, en qué orden'. Los dos se complementan.

## Métricas de finalización diferida: hacer visible la suspensión silenciosa

Es posible que ya se haya concluido un pago con estado `FinalizePending` por parte del PSP, aunque el resultado aún no se haya mostrado al cliente. Esta ventana es normal, pero se debe medir su duración.```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
```Estas métricas también determinan "con qué urgencia" debe escanear el trabajador de conciliación. Si `deferred_finalize_age_seconds` está aumentando, es posible que el problema no esté en un pago único, sino en la canalización final o el procesamiento del webhook.

## Diseño del panel: visibilidad operativa

| Paneles | Espectáculos | Activador de acción |
| --- | --- | --- |
| Recuento finalizado aplazado | Volumen de pago instalado | Aumento continuo → revisión del oleoducto |
| Finalizar edad P99 | Peor retraso | Superación del SLA → de guardia |
| Brecha de registro de pasos | Paso faltante (no se ha recibido ningún Webhook) | Problema de entrega de webhook |
| Tasa de conflicto de versiones | Intensidad de carrera | Ajuste de concurrencia |

## Distinciones frecuentemente confusas```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
```## Registro frente a registro de eventos de pasos frente a auditoría

| Género | Pregunta | Ejemplo |
| --- | --- | --- |
| Registro estructurado | Detalle instantáneo del evento | Webhook recibido, latencia = 120 ms |
| Registro de eventos de pasos | Secuencia del ciclo de vida | Cargo enviado → Webhook recibido → Finalizar |
| Registro de auditoría | Intervención humana/de proceso | El operador X activó la curación manual |

## Lista de verificación de observabilidad

1. ¿Cada línea de registro, tramo de seguimiento y etiqueta de métrica lleva una identificación de pago?
2. ¿El registro de eventos de pasos es solo para agregar e incluye todos los pasos significativos?
3. ¿Están definidas las métricas `deferred_finalize_count` y `deferred_finalize_age_seconds`?
4. ¿Existe una alerta basada en SLA para la edad de finalización P99?
5. ¿Es posible rastrear la ruta completa desde el registro de pasos, desde el pago hasta el estado del terminal, con un ID de pago?
6. ¿Los registros corregidos por el trabajador de conciliación se escriben en el registro de pasos?

## Lo que debes recordar de este artículo

1. La identificación del pago es la columna vertebral de toda observabilidad; Solicitar identificación por sí sola no es suficiente.
2. El registro de eventos de pasos es el cronograma del pago; Lleva el orden que las métricas no pueden mostrar.
3. Las métricas de finalización diferida hacen que pasar un rato tranquilo sea medido y estimulante.
4. La observabilidad no es un lujo; Determina qué buscan la conciliación y la guardia.

> Cuando un pago está bloqueado, "veamos los registros" no es suficiente; Necesita un registro de eventos de pasos y una métrica de finalización diferida que mostrará en qué paso se encuentra en cuestión de segundos con la identificación del pago.

En la siguiente sección, creamos procesos de recuperación y runbooks sobre esta visibilidad: primero la automatización, la intervención humana dentro de los muros de la singularidad.