docs(docs): describe durable jobs, telemetry, and bundle limits

Зафиксированы очередь job, семантика метрик, лимиты бандла и исходящих запросов, а также чеклист продакшена для пула соединений.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/metrics-semantics.md

@@ -0,0 +1,21 @@
+# Смысл метрик хранилища
+
+Метрики `/metrics` с префиксом `evobgp_` описывают разные источники данных. Их нельзя складывать в один показатель «маршруты сейчас» или «сеть здорова».
+
+| Метрика | Источник и смысл |
+| --- | --- |
+| `stored_revision_materialized_prefixes_max`, `stored_revision_materialized_prefixes_sum` | Максимум и сумма `materialized_prefix_count` **по всем сохранённым ревизиям**, включая историю. Не текущие маршруты, не опубликованная или применённая конфигурация. |
+| `inventory_bgp_peers` | Число настроенных BGP peers в хранилище, независимо от `enabled` и фактической сессии. |
+| `stored_bgp_peer_session_state{state}` | Число peers по сохранённому `meta_json.session_state`. Это последнее записанное значение или intent, а не свежий опрос BIRD. Значения `state` ограничены стандартными состояниями BGP, `unknown` и `other`. |
+| `store_metrics_collection_success` | `1`, если агрегаты хранилища прочитаны; `0`, если чтение БД завершилось ошибкой. При `0` остальные метрики хранилища в данном scrape отсутствуют. |
+| `bird_bgp_sessions_established`, `bird_protocols_scrape_success` | Локальный опрос BIRD процесса API; не охватывает все remote speakers. При ошибке опроса число Established не следует трактовать как достоверный нуль. |
+
+Старые `materialized_prefixes_max/sum`, `bgp_peers_configured_total` и `bgp_peer_sessions{state}` продолжают экспортироваться с прежним смыслом на переходный период. Они устаревают; правила и dashboards нужно перевести на явные имена перед удалением старых рядов. Исторические ревизии могут увеличить оба ряда `*_sum`, поэтому использовать их как KPI текущих маршрутов нельзя.
+
+Группы desired, published, confirmed applied и observed live, а также общий статус multi-speaker требуют отдельной реализации и политики свежести. Здесь эти метрики пока не объявлены.
+
+## Circuit breaker внешних запросов
+
+`upstream_breaker_open{host}` — последнее наблюдение breaker при запросе, не фоновая проверка доступности сервера. Истечение cooldown само по себе не обновляет gauge до следующего обращения; по этой метрике нельзя выводить свежий outage upstream.
+
+Cache ограничен 1024 hostname на процесс, имена нормализованы в нижний регистр без завершающей точки; порты одного hostname разделяют breaker. Новая identity при заполненном cache отклоняется до соединения. Закрытые записи после 10 минут простоя удаляются вместе с текущим label set при следующем обслуживании cache; активные запросы и ещё открытый cooldown не вытесняются. Это ограничивает текущую память и scrape cardinality, но не удаляет исторические series из TSDB Prometheus.