Skip to main content

Flaree Agent

info

Перевод в процессе / Translation in progress. See русская версия.

Flaree Agent — это .NET NativeAOT-бинарь. Он запускается рядом с инфраструктурой клиента. Агент устанавливается на тот же хост (или в тот же кластер), что и наблюдаемые приложения. Агент выполняет HTTP- и TCP-checks против локальных и соседних сервисов. Агент отправляет heartbeat'ы в Flaree API. Агент собирает логи и метрики из включённых источников. Агент принимает OTLP-трафик от приложений на loopback-интерфейсе.

Egress-only connectivity​

Агент работает исключительно через исходящие HTTPS-соединения до Flaree API. Агенту не нужны входящие порты, открытые наружу. Единственный слушающий сокет агента — OTLP-receiver, биндящийся на loopback. Это упрощает firewall-политики: достаточно разрешить outbound до ingest.flaree.ru:443. Это исключает внешние поверхности атаки: агент не светит ни одного порта в публичную сеть. Это совместимо с корпоративными NAT и прокси: агент поддерживает HTTP-proxy через переменную HTTPS_PROXY и ключ proxy в agent.yaml.

OTLP loopback receiver​

OTLP-receiver агента биндится только на 127.0.0.1. Агент отказывается стартовать, если в конфиге указан host: 0.0.0.0 или любой не-loopback адрес. Это гарантирует, что OTLP-трафик никогда не покидает хост в открытом виде. Receiver принимает OTLP исключительно в hand-parsed JSON. Receiver не поддерживает Protobuf-кодирование OTLP. Причина — сохранение NativeAOT-совместимости: Protobuf-библиотеки используют рантайм-рефлексию, которая ломает AOT-сборку. JSON парсится через System.Text.Json.JsonDocument без генерации типов. Приложения на том же хосте могут слать OTLP на http://127.0.0.1:4318/v1/logs и http://127.0.0.1:4318/v1/metrics с заголовком Content-Type: application/json.

Auto-update через channel и min-version​

Агент поддерживает автоматическое обновление. Канал обновления задаётся ключом update.channel и принимает значения stable или canary. При ответе Flaree API 401 minimum_version_required агент инициирует обновление немедленно, не дожидаясь планового цикла. Обновление гейтится по min-version: агент скачивает релиз, только если заявленная серверной стороной минимальная версия выше установленной. Обновление проверяет подпись бинаря перед заменой. Автообновление отключается переменной окружения FLAREE_AGENT_AUTO_UPDATE=false. В этом случае агент продолжает работать на текущей версии, а при 401 minimum_version_required логирует ошибку и помечает статус в heartbeat.

SQLite spool при отключениях​

При сетевых ошибках и ответах 5xx от Flaree API агент буферизует исходящие батчи в локальный SQLite-файл. Путь к спулу задаётся ключом spool.path или переменной FLAREE_SPOOL_PATH. Спул имеет ограничение по размеру на диске; при переполнении старые батчи вытесняются. После восстановления канала агент возобновляет отправку из спула в порядке FIFO. Повторные попытки используют экспоненциальный backoff с jitter: базовая задержка удваивается до верхней границы, плюс случайная добавка. Для 429 quota_exceeded backoff идёт до reset_at, а заголовок Retry-After имеет приоритет как authoritative значение.

Маскирование секретов​

Маскирование секретов происходит на агенте до отправки данных в Flaree API. Пароли, токены, bearer-заголовки и API-ключи в HTTP-headers заменяются placeholder-ами вида ***. Чувствительные поля в HTTP-bodies (на основе имён полей и известных паттернов) также маскируются до сериализации. Backend Flaree никогда не видит plaintext секретов: до ingress-слоя данные уже обработаны. Это означает, что даже при компрометации серверной стороны сырые секреты клиента не утекут. Список masking-правил задаётся в agent.yaml в секции logs.redact и расширяется пользовательскими паттернами.

Дальше​