Payment Orchestrator

Тема

06.01 Monitoring, Metrics And Alerts ​

Статус: черновик для обсуждения

1. Назначение документа ​

Этот документ описывает monitoring / metrics / alerts requirements для MVP.

Цель:

  • видеть проблемы системы до того, как о них сообщит merchant;
  • понимать падение success rate;
  • отслеживать provider/SUB MID issues;
  • отслеживать webhook delivery problems;
  • отслеживать suspicious provider callbacks;
  • иметь базовые business metrics по transactions.

2. Monitoring stack ​

В MVP metrics должны быть доступны через:

text
Prometheus

Prometheus является обязательным monitoring layer.

Grafana / dashboards могут использоваться internal ops team, но отдельный Back Office monitoring dashboard в MVP не нужен.

3. Back Office visibility ​

Monitoring в MVP является internal ops capability.

Platform users не обязаны видеть monitoring links / health status в Back Office.

Back Office UI dashboard для monitoring в MVP не нужен.

Если в будущем потребуется operational dashboard в Back Office, это должно быть описано отдельно.

4. Success rate alerts ​

Нужны alerts на падение success rate.

Success rate должен отслеживаться по:

  • system;
  • merchant;
  • payment method;
  • provider / SUB MID.

Точные thresholds должны быть предложены development/ops team.

Пример:

text
Alert: success rate for SUB MID X dropped below threshold for N minutes.

5. Error rate alerts ​

Нужны alerts на рост error rate.

Error rate должен отслеживаться по:

  • error category;
  • error code;
  • merchant;
  • payment method;
  • provider / SUB MID, если применимо;
  • system level.

Error categories должны соответствовать Error Mapping document:

  • VALIDATION;
  • ROUTING;
  • VELOCITY;
  • PROVIDER;
  • WEBHOOK;
  • SYSTEM;
  • EXPIRED;
  • CANCELED.

6. Webhook delivery alerts ​

Нужны alerts на webhook delivery failures.

Минимально:

  • рост failed webhook attempts;
  • exhausted webhook retries;
  • merchant endpoint consistently returns non-2xx;
  • webhook delivery latency, если development/ops team решит это добавить.

Webhook failures должны быть связаны с:

  • merchant;
  • transaction;
  • webhook URL;
  • status/event type.

7. Provider callback validation alerts ​

Нужны alerts на provider callback validation failures / suspicious callbacks.

Минимально alert должен срабатывать на:

  • amount/currency mismatch;
  • callback does not match selected SUB MID / SUB MID AGGREGATOR;
  • invalid provider signature/auth, если provider supports validation;
  • suspicious callback;
  • high number of rejected callbacks.

Unknown provider statuses не обязательно должны создавать alert, если они просто сохраняются как ignored.

Но metrics по ignored/unknown statuses должны быть доступны.

8. Queue lag / processing delay ​

В MVP alerts на queue lag / processing delay не обязательны.

Это может быть добавлено development/ops team как technical monitoring, но продуктово не является MVP requirement.

9. Stuck transactions ​

В MVP alerts на transactions stuck in non-final status дольше X минут не обязательны.

Expiration logic должна переводить expired transactions в нужный status, но отдельный alert на stuck transactions не входит в MVP product requirements.

Если development/ops team решит добавить такой alert технически, это допустимо, но не является обязательным для MVP acceptance.

10. Required business metrics ​

Минимальные business metrics:

  • created transaction count;
  • completed transaction count;
  • failed transaction count;
  • rejected transaction count;
  • transaction amount;
  • success rate;
  • provider latency.

Эти metrics должны быть доступны с labels/dimensions, где применимо:

  • merchant;
  • brand;
  • payment method;
  • provider / SUB MID;
  • status;
  • currency;
  • error code;
  • error category.

11. Provider latency ​

Provider latency должна измерять время provider interaction.

Минимально:

  • time to provider response for request;
  • time to provider payment URL received, если применимо;
  • callback latency, если возможно определить expected baseline.

Точный latency definition должен быть предложен development/ops team, чтобы metrics были consistent.

12. Metrics labels and sensitive data ​

Metrics labels не должны содержать sensitive data.

Нельзя использовать как labels:

  • customer email;
  • customer full name;
  • API key;
  • provider credentials;
  • raw provider error message;
  • webhook URL full value, если она может содержать sensitive data;
  • any personal/sensitive data.

Labels должны быть low-cardinality where possible.

13. Acceptance Criteria ​

Monitoring / Metrics / Alerts считаются согласованными для MVP, если:

  • Metrics доступны через Prometheus.
  • Back Office monitoring dashboard в MVP не нужен.
  • Monitoring links / health status в Back Office не нужны.
  • Alerts есть на падение success rate по system.
  • Alerts есть на падение success rate по merchant.
  • Alerts есть на падение success rate по payment method.
  • Alerts есть на падение success rate по provider / SUB MID.
  • Alerts есть на рост error rate по error category/code.
  • Alerts есть на webhook delivery failures.
  • Alerts есть на provider callback validation failures / suspicious callbacks.
  • Alerts на queue lag / processing delay не являются MVP requirement.
  • Alerts на stuck transactions не являются MVP requirement.
  • Metrics включают created/completed/failed/rejected transaction count.
  • Metrics включают transaction amount.
  • Metrics включают success rate.
  • Metrics включают provider latency.
  • Metrics labels не содержат sensitive data.

14. Open Questions ​

Product open questions отсутствуют.

Technical/ops follow-up:

  1. Определить exact Prometheus metric names.
  2. Определить exact labels для каждой metric.
  3. Определить success rate thresholds.
  4. Определить error rate thresholds.
  5. Определить webhook failure alert thresholds.
  6. Определить provider callback suspicious alert thresholds.
  7. Определить Grafana dashboards for internal ops.