Интеграция OTLP

Flaree принимает метрики и логи по OTLP/JSON двумя путями: через loopback-приёмник агента на том же хосте или напрямую в публичный ingestion-шлюз. Traces принимаются в обоих режимах, но отбрасываются — Flaree их не хранит. Концепция обоих режимов — в OTLP-концепции.

Предварительные требования

• OpenTelemetry SDK в приложении с экспортом OTLP/HTTP и JSON-кодированием (http/json); Protobuf не поддерживается.
• Для режима через агент: агент Flaree на том же хосте, приложение может достучаться до 127.0.0.1:4318.
• Для прямого ingestion: токен агента из дашборда и исходящий HTTPS до api.flaree.ru:443.

Минимальная конфигурация

Через агент — включите приёмник в /etc/flaree-agent/agent.yaml (или FLAREE_AGENT_OTLP_ENABLED=true) и перезапустите агента:

otlp:
  enabled: true

В приложении направьте экспортер на loopback:

OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

Прямой ingestion — без агента, с токеном в заголовке:

OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.flaree.ru/otlp
OTEL_EXPORTER_OTLP_HEADERS=X-Flaree-Token=<токен>

SDK сам добавит пути /v1/metrics, /v1/logs, /v1/traces.

Полная конфигурация

Все ключи секции otlp: в agent.yaml:

Ключ	Тип	По умолчанию	Описание
enabled	bool	false	Включает приёмник. Env: FLAREE_AGENT_OTLP_ENABLED.
host	string	127.0.0.1	Адрес прослушивания. Только loopback — с другим значением приёмник откажется стартовать. Env: FLAREE_AGENT_OTLP_HOST.
port	number	4318	Порт приёмника. Env: FLAREE_AGENT_OTLP_PORT.
max_request_bytes	number	4194304	Лимит тела запроса (4 МБ); превышение — HTTP 413.

Приёмник слушает POST /v1/metrics, /v1/logs и /v1/traces; traces подтверждаются и отбрасываются. Принятые данные уходят на бэкенд через тот же транспорт, что и остальная телеметрия агента, — с буферизацией при сбоях сети. Приложению не нужен ни собственный токен, ни выход в интернет.

Защита двойная: bind только на loopback плюс отклонение запросов с не-loopback адресов на рантайме. Прямой ingestion (/otlp/v1/{metrics,logs,traces}) аутентифицируется заголовком X-Flaree-Token и подчиняется квотам: при 429 уважайте Retry-After.

к сведению

Не путайте приёмник с экспортером: переменная FLAREE_AGENT_OTEL_ENDPOINT отправляет телеметрию самого агента в ваш OTLP-коллектор и к приёму данных приложений отношения не имеет.

Проверка работы

• Убедитесь, что приёмник слушает порт 4318 после перезапуска агента.
• Отправьте пустой батч и проверьте код ответа.
• В дашборде метрики приложения появятся в списке доступных для привязки в течение пары минут.

# Приёмник агента отвечает
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Content-Type: application/json' -d '{}' \
  http://127.0.0.1:4318/v1/metrics
# 200

# Прямой ingestion
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Content-Type: application/json' -H "X-Flaree-Token: <токен>" \
  -d '{}' https://api.flaree.ru/otlp/v1/metrics

Troubleshooting

• Приёмник не отвечает или данные не доходят до дашборда — OTLP не принимает данные.
• HTTP 429 при прямом ingestion — превышена квота.
• HTTP 413 — батч больше max_request_bytes; уменьшите send_batch_size в SDK или поднимите лимит.

Связанные страницы: OTLP-концепция · привязка метрик · API.