From 4cd5131f8ddcccbdd5c3370a7f570aa7a03baa4a Mon Sep 17 00:00:00 2001
From: Naeel <naeel@ngcloud.ru>
Date: Sun, 12 Apr 2026 12:34:53 +0300
Subject: [PATCH] doc: add billing and metrics documentation

---
 README.md                  |  1 +
 doc/billing-and-metrics.md | 95 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 doc/billing-and-metrics.md

diff --git a/README.md b/README.md
index f69e53b..2f6186d 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,7 @@ aws sqs send-message \
 ## Документация
 
 - [PLAN.md](PLAN.md) — детальный план разработки
+- [doc/billing-and-metrics.md](doc/billing-and-metrics.md) — биллинг и Prometheus-метрики
 - [doc/byoc-credentials.md](doc/byoc-credentials.md) — BYOC интеграция
 
 ## Ссылки
diff --git a/doc/billing-and-metrics.md b/doc/billing-and-metrics.md
new file mode 100644
index 0000000..e7be949
--- /dev/null
+++ b/doc/billing-and-metrics.md
@@ -0,0 +1,95 @@
+# Биллинг и метрики
+
+## Биллинг (Usage Tracking)
+
+Каждая успешная SQS-операция записывается в PostgreSQL — таблица `sqs_usage_records`.
+
+### Что записывается
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `id` | BIGSERIAL | PK, автоинкремент |
+| `tenant_id` | TEXT | Идентификатор тенанта |
+| `operation` | TEXT | SQS-операция (SendMessage, ReceiveMessage и т.д.) |
+| `queue_name` | TEXT | Имя очереди |
+| `msg_count` | INTEGER | Количество сообщений в запросе |
+| `msg_bytes` | BIGINT | Объём тел сообщений в байтах |
+| `recorded_at` | TIMESTAMPTZ | Время записи |
+
+Индекс: `(tenant_id, recorded_at)`.
+
+### Конфигурация
+
+Billing включается автоматически если заданы переменные окружения:
+
+| Переменная | Пример | Описание |
+|-----------|--------|----------|
+| `BILLING_PG_HOST` | `postgresqlk8s-master.xxx.svc.cluster.local` | Хост PostgreSQL |
+| `BILLING_PG_PORT` | `5432` | Порт |
+| `BILLING_PG_DATABASE` | `sqsdb` | Имя базы |
+| `BILLING_PG_USER` | `super` | Пользователь |
+| `BILLING_PG_PASSWORD` | `***` | Пароль |
+| `BILLING_PG_SSLMODE` | `disable` | SSL режим |
+
+Если `BILLING_PG_HOST` не задан — billing отключён, SQS работает как раньше без зависимости от PG.
+
+### Доступ к данным
+
+Подключение к БД из кластера:
+
+```bash
+kubectl exec -it pod/postgresqlk8s-master-0 \
+  -n dc5db45d-f8b4-4fd0-ad33-ec4dd017f2d5 \
+  -- psql -U super -d sqsdb
+```
+
+Примеры запросов:
+
+```sql
+-- Последние 20 записей
+SELECT * FROM sqs_usage_records ORDER BY recorded_at DESC LIMIT 20;
+
+-- Статистика по операциям
+SELECT operation, COUNT(*), SUM(msg_count), SUM(msg_bytes)
+FROM sqs_usage_records GROUP BY operation ORDER BY count DESC;
+
+-- По тенанту за сегодня
+SELECT operation, COUNT(*) FROM sqs_usage_records
+WHERE tenant_id = 'MY_TENANT' AND recorded_at >= CURRENT_DATE
+GROUP BY operation;
+
+-- Объём трафика по дням
+SELECT DATE(recorded_at) AS day, SUM(msg_bytes) AS total_bytes
+FROM sqs_usage_records GROUP BY day ORDER BY day DESC;
+```
+
+---
+
+## Prometheus-метрики
+
+Сервис отдаёт метрики на endpoint `/metrics` в формате Prometheus. Victoria Metrics скрейпит их через VMServiceScrape каждые 30 секунд.
+
+### Доступные метрики
+
+| Метрика | Тип | Labels | Описание |
+|---------|-----|--------|----------|
+| `sqs_requests_total` | Counter | tenant, operation | Количество SQS-запросов |
+| `sqs_request_bytes_total` | Counter | tenant, operation | Объём тел запросов (байты) |
+| `sqs_request_duration_seconds` | Histogram | operation | Latency операций (1ms–30s) |
+| `sqs_errors_total` | Counter | operation | Количество ошибок (HTTP ≥ 400) |
+| `sqs_queues_count` | Gauge | tenant | Текущее количество очередей |
+| `sqs_messages_count` | Gauge | tenant | Текущее количество сообщений |
+
+### Просмотр метрик
+
+Напрямую с пода:
+
+```bash
+kubectl exec -it deploy/shared-sqs -n shared-sqs \
+  -- wget -qO- http://localhost:9090/metrics | grep sqs_
+```
+
+### VMServiceScrape
+
+Файл: `deployments/k8s/vmservicescrape.yaml` — автоматический scrape Victoria Metrics.
+Namespace `shared-sqs` помечен лейблом `shturval.tech/system-namespace` для обнаружения VMAgent-ом.