Глоссарий

Единый словарь терминов Flaree, чтобы документация, интерфейс продукта и API-ответы опирались на одинаковое значение каждого понятия.

Agent

Агент Flaree — статический бинарник .NET NativeAOT, устанавливаемый рядом с инфраструктурой клиента. Он выполняет Check-проверки, собирает логи и метрики, принимает OTLP/HTTP на loopback и отправляет всё egress-only в бэкенд. При недоступности сети данные буферизуются в памяти или в SQLite-буфере. Автообновление проверяет манифест каждые 6 часов и умеет принудительно обновлять при серверном minimumVersion. Подробности — в концепции агента и справочнике agent.yaml.

Organization

Organization — верхнеуровневый Tenant в Flaree, владеющий подпиской, тарифным планом, лимитами Quota и сроками Retention. Одна организация содержит один или несколько Workspace, в которых живут компоненты, проверки и правила. Все данные ingestion и запросов фильтруются по org_id, поэтому Organization служит и единицей биллинга, и изоляционным периметром для логов, метрик и инцидентов.

Workspace

Workspace — логический скоуп внутри Organization, группирующий набор Component, проверок и правил под одним именем. Типичное применение — разделение на среды prod/stage/dev или на команды-владельцы. Права доступа к отдельным workspaces настраиваются раздельно, но биллинг, квоты и retention считаются на уровне Organization. Workspace выбирается в дашборде и определяет, какие компоненты и инциденты вы видите.

Component

Component — проверяемый объект в Flaree: сервис, база данных, API-эндпоинт, контейнер или другой элемент инфраструктуры. К компоненту привязываются Check-проверки и правила, определяющие, когда открывать Incident. Компоненты живут внутри Workspace и являются основной единицей, на которой строятся дашборды, статусы и ленты инцидентов.

Check

Check — активная проверка доступности или целостности компонента: HTTP-запрос, TCP-коннект, запрос к базе (Postgres, MySQL, Redis, Mongo, RabbitMQ, Kafka) или приём Heartbeat. Проверки настраиваются в дашборде, а Agent получает их как jobs через GET /api/agent/config. Результат каждой попытки становится checkin-записью со статусом, задержкой и кодом ответа — по потоку checkins строятся SLA и графики доступности.

Rule (Log/Metric)

Rule — условие, при котором Flaree открывает или закрывает Incident. LogRule реагирует на шаблон строки, регулярное выражение или долю ошибок в скользящем окне. MetricRule сравнивает агрегаты avg, max, p95, count по метрике с порогом. Правила оцениваются событийно — по факту вставки батча логов или метрик, а не по таймеру. У каждого правила настраиваются Flap-Guard и Cooldown; подробнее — в Rules engine.

Incident

Incident — инцидент, который Flaree открывает, когда правило с учётом flap-guard подтверждений и cooldown-паузы признаёт ситуацию аномальной. У инцидента есть время начала, ссылка на Component и правило-источник, снапшот триггерных данных и журнал уведомлений. Закрывается инцидент по recovery-условию того же правила. Уведомления по инциденту уходят в Telegram, email или webhook.

Tenant

Tenant — уровень изоляции данных одной Organization от всех остальных. Фактически tenant-ом выступает org_id: и ingestion-пайплайн, и все запросы к хранилищам ставят org_id первым предикатом фильтрации. Это условие enforce-ится статическим анализатором, который валит сборку при попытке написать cross-org запрос. Даже отладочные дашборды и фоновые задачи никогда не читают данные без tenant-фильтра.

OTLP

OTLP — OpenTelemetry Protocol, стандартный транспорт телеметрии. У агента два независимых OTLP-механизма: receiver принимает OTLP/JSON от приложений на том же хосте строго на loopback 127.0.0.1:4318 и пересылает данные в SaaS, а exporter отправляет метрики самого агента во внешний коллектор через FLAREE_AGENT_OTEL_ENDPOINT. Receiver понимает только JSON — Protobuf несовместим с NativeAOT. Подробности — в концепции OTLP.

Ingestion

Ingestion — stateless-шлюз, принимающий поток логов и метрик от агентов на /api/agent/logs и /api/agent/metrics, а также OTLP напрямую на /otlp/v1/*. Шлюз проверяет agent token, считает Quota и передаёт валидные батчи в очередь на обработку. Доменной логики правил и уведомлений здесь нет — это сознательный дизайн ради горизонтального масштабирования и быстрых ответов. Маршруты и коды ошибок — в справочнике API.

Quota

Quota — лимиты тарифного плана на объём логов и метрик, принимаемых платформой. Квота проверяется только в шлюзе Ingestion, до записи в очередь. При превышении шлюз возвращает HTTP 429 с кодом quota_exceeded, полем reset_at и заголовком Retry-After — заголовок приоритетен как authoritative backoff. Agent приостанавливает отправку до указанного времени, сохраняя данные в буфере. См. квоты и retention.

Retention

Retention — срок хранения исторических данных (логов, метрик, checkins), привязанный к тарифному плану каждой Organization. Применяется per-org, а не через единый глобальный TTL: удалением занимается ежедневный фоновый джоб, вычисляющий окно хранения по тарифу организации. Такой подход позволяет держать разные retention-периоды для разных организаций и быстро реагировать на смену плана. Текущие значения видны в настройках workspace.

Flap-Guard

Flap-Guard — защита правила от «дребезга»: требование, чтобы триггер подтвердился подряд N раз, прежде чем Flaree откроет Incident. Без неё единичный всплеск ошибок или кратковременный провал метрики немедленно породил бы шумный алерт. Flap-guard задаётся на каждом правиле отдельно и отсчитывается в подряд идущих оценках, а не в секундах. Для recovery используется симметричный счётчик, чтобы инциденты не закрывались по первому «зелёному» батчу.

Cooldown

Cooldown — минимальная пауза в секундах между повторными открытиями Incident по одному и тому же правилу на одном компоненте. После закрытия предыдущего инцидента правило не реагирует на новые триггеры, пока cooldown-окно не истечёт, даже если условие снова выполняется. Настройка защищает on-call от каскадных алертов при длительной нестабильности источника и даёт время на восстановление. Задаётся на уровне правила.

Heartbeat

Heartbeat — ежеминутный POST-запрос агента на /api/agent/heartbeat с версией, uptime и метриками CPU/RAM, которым агент подтверждает, что жив и продолжает собирать данные. Если heartbeat не приходит в течение порогового окна, агент помечается в дашборде как offline. Отсутствие heartbeat служит первым сигналом проблем с хостом или сетью клиента; сценарий разбора — в Agent offline.