From 5db7723854999e3fa1d3be9d6ba1663f9f368ba2 Mon Sep 17 00:00:00 2001
From: Naeel <naeel@nubes.ru>
Date: Sun, 12 Apr 2026 12:41:37 +0300
Subject: [PATCH] doc: add billing usage tracking documentation

---
 BILLING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 README.md  |  4 ++++
 2 files changed, 48 insertions(+)
 create mode 100644 BILLING.md

diff --git a/BILLING.md b/BILLING.md
new file mode 100644
index 0000000..3c131d9
--- /dev/null
+++ b/BILLING.md
@@ -0,0 +1,44 @@
+# Биллинг — учёт использования SQS
+
+shared-SQS записывает каждую успешную SQS-операцию в PostgreSQL для учёта использования.
+
+## Что записывается
+
+| Поле | Описание |
+|------|----------|
+| `tenant_id` | Идентификатор тенанта |
+| `operation` | SQS-операция (SendMessage, ReceiveMessage и т.д.) |
+| `queue_name` | Имя очереди |
+| `msg_count` | Количество сообщений в запросе |
+| `msg_bytes` | Объём тел сообщений в байтах |
+| `recorded_at` | Время записи |
+
+## Доступ к данным
+
+Подключение к БД из кластера:
+
+```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;
+```
diff --git a/README.md b/README.md
index 05827de..f16ceec 100644
--- a/README.md
+++ b/README.md
@@ -210,6 +210,10 @@ AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... bash hardcore_test.sh
 - purge
 - queue lifecycle
 
+## Биллинг
+
+Учёт использования SQS-операций — см. [BILLING.md](BILLING.md).
+
 ## Сравнительные тесты
 
 Краткий пользовательский summary лежит в файле `BENCHMARK-COMPARISON.md`.