Глоссарий
Перевод в процессе / Translation in progress. See русская версия.
Единый словарь терминов Flaree, чтобы документация, интерфейс продукта и API-ответы опирались на одинаковое значение каждого понятия.
Agent
Агент Flaree — это .NET NativeAOT бинарь, который устанавливается рядом с инфраструктурой клиента и собирает результаты checks, логи и метрики. Он работает egress-only, не принимает входящих соединений извне, умеет принимать OTLP/HTTP на loopback-адресе, буферизует данные в SQLite spool при офлайне и поддерживает auto-update по каналу и минимальной версии. Все секреты маскируются прямо на агенте до отправки.
Organization
Organization — верхнеуровневый tenant в Flaree, владеющий подпиской, тарифным планом и лимитами квот. Одна организация содержит один или несколько workspaces, в которых живут компоненты, checks и правила. Все данные ingestion и запросов всегда фильтруются по org_id, поэтому Organization служит и административной единицей биллинга, и изоляционным периметром для логов, метрик и инцидентов.
Workspace
Workspace — логический скоуп внутри Organization, который группирует набор компонентов, checks и правил под одним именем. Типичное применение — разделение на среды prod/stage/dev или на команды-владельцы. Агент при регистрации указывает workspace, и все отправляемые им данные автоматически получают соответствующую привязку. Права доступа к отдельным workspaces можно настраивать раздельно, но биллинг и квоты всё равно считаются на уровне Organization.
Component
Component — проверяемый объект в Flaree: сервис, база данных, API-эндпоинт, контейнер или любой другой элемент инфраструктуры, к которому имеет смысл привязывать мониторинг. К каждому компоненту привязываются checks (HTTP, TCP, heartbeat) и правила (LogRule, MetricRule), определяющие, когда открывать инцидент. Компоненты живут внутри Workspace и являются основной единицей, на которой строятся дашборды и ленты инцидентов.
Check
Check — отдельная активная проверка доступности или целостности компонента: HTTP-запрос, TCP-пробник или приём heartbeat от удалённого сервиса. Check выполняется либо агентом на стороне клиента, либо плановщиком на backend, с заданным интервалом. Результат каждой попытки становится checkin-записью с полями статуса, задержки и кодом ответа. Именно по потоку checkins строятся SLA, графики доступности и один из источников, из которых правила умеют поднимать инциденты.
Rule (Log/Metric)
Rule — условие, при выполнении которого Flaree открывает или закрывает инцидент. LogRule реагирует на шаблон строки, регулярное выражение или долю сообщений с уровнем error в скользящем окне. MetricRule сравнивает агрегаты avg, max, p95 или count по метрике с заданным порогом. Обе разновидности правил оцениваются событийно на LogsBatchInserted и MetricsBatchInserted, а не по настенному таймеру. У каждого правила настраиваются flap-guard и cooldown.
Incident
Incident — инцидент, который Flaree открывает, когда правило с учётом flap-guard подтверждений и cooldown-паузы признаёт текущую ситуацию аномальной. У инцидента есть время начала, ссылка на компонент и на правило-источник, снапшот данных, вызвавших триггер, и журнал уведомлений. Закрывается инцидент по recovery-условию того же правила: пропаданию ошибок из окна или возврату метрики в границы порога. По инциденту уведомления отправляются в Telegram и email через worker-notif.
Tenant
Tenant — логический уровень изоляции данных одной Organization от всех остальных. В Flaree tenant-ом фактически выступает org_id: и ingestion-пайплайн, и все пользовательские запросы к ClickHouse и Postgres всегда ставят org_id первым предикатом в WHERE. Это условие enforce-ится Roslyn-анализатором, который валит сборку при попытке написать cross-org запрос. Даже отладочные дашборды и фоновые задачи никогда не читают данные без tenant-фильтра.
OTLP
OTLP — OpenTelemetry Protocol, стандартный транспорт телеметрии OpenTelemetry. Агент Flaree встраивает OTLP/HTTP-приёмник, который биндится исключительно на loopback 127.0.0.1 и принимает полезную нагрузку в JSON без зависимости от Protobuf. Такое ограничение сознательное: сохранение NativeAOT-совместимости агента не позволяет подключать тяжёлые protobuf-рантаймы. Приложения клиента экспортируют логи и метрики в этот локальный приёмник, а агент пересылает их в Flaree.Ingestion через обычный egress-канал.
Ingestion
Ingestion — stateless-gateway Flaree.Ingestion, который принимает весь поток телеметрии от агентов. Сервис проверяет agent-токен, валидирует минимальную версию, считает квоту через IIngestQuotaPolicy и пушит валидные батчи в Redis Streams для дальнейшей обработки воркерами. Никакой доменной логики правил или уведомлений здесь не живёт — это сознательный дизайн, чтобы ingestion можно было горизонтально масштабировать и отвечать быстро. Все ошибки возвращаются клиенту в формате error из AGENTS.md.
Quota
Quota — лимиты тарифного плана на объём logs, metrics и traces, принимаемых платформой. Проверка квоты живёт строго в Flaree.Ingestion через IIngestQuotaPolicy, чтобы отсекать лишнее до записи в Redis Streams и не тратить I/O хранилищ. При превышении ingestion возвращает HTTP 429 с кодом ошибки quota_exceeded, полем reset_at и заголовком Retry-After. Агент обязан уважать эти значения и приостанавливать отправку до указанного времени, сохраняя данные в SQLite spool.
Retention
Retention — срок хранения исторических данных (логов, метрик, checkins, traces), индивидуально привязанный к тарифному плану каждой Organization. Enforce-ится per-org, а не через единый глобальный TTL ClickHouse: удалением занимается RetentionWorker, работающий как ежедневный Hangfire-recurring-джоб в хосте Flaree.Worker. Такой подход позволяет одновременно держать разные retention-периоды для разных организаций, быстро откатывать изменения плана и не терять данные при временных сбоях воркера. Retention-политики отображаются пользователю в настройках workspace.
Flap-Guard
Flap-Guard — защита от «дребезга» правила: требование, чтобы триггер подтвердился подряд N раз (integer consecutive confirmations) прежде, чем Flaree откроет инцидент. Без этой настройки единичный всплеск ошибок или кратковременный провал метрики немедленно породил бы шумный алерт. Flap-guard задаётся на каждом правиле отдельно и отсчитывается в подряд идущих оценках, а не в секундах. Для recovery обычно используется симметричный счётчик, чтобы инциденты не закрывались по первому же «зелёному» батчу.
Cooldown
Cooldown — минимальная пауза в секундах между повторными открытиями инцидента одного и того же правила на одном компоненте. После закрытия предыдущего инцидента правило не реагирует на новые триггеры, пока cooldown-окно не истечёт, даже если условие снова выполняется. Настройка защищает on-call от каскадных алертов при длительной нестабильности источника и даёт команде время на применение патча или восстановление. Значение cooldown задаётся на уровне правила в секундах.
Heartbeat
Heartbeat — регулярный POST-запрос агента на эндпоинт /api/agent/heartbeat, которым он подтверждает, что жив и продолжает собирать данные. В ответе backend возвращает статусы токена, текущую минимальную требуемую версию и служебные настройки. Если heartbeat не приходит в течение порогового окна, агент автоматически переводится в offline-статус и подсвечивается в дашборде. Отсутствие heartbeat также используется как триггер для правил-мониторов доступности самих агентов и служит первым сигналом проблем с сетью клиента.