Skip to main content

Интеграция OTLP

info

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

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

РежимEndpointКогда выбирать
Через агент (loopback)http://127.0.0.1:4318Агент уже стоит на хосте, нужны маскирование секретов и spool при сетевых сбоях, есть приватные сигналы (db.statement, заголовки авторизации).
Прямой ingestion (agentless)https://api.flaree.ru/otlp/v1Serverless / managed-runtime без агента (Lambda, Cloud Functions), быстрая интеграция в существующий OpenTelemetry-стек, не нужны локальный буфер и redact на агенте.

Дальше — единая структура для обоих режимов: prerequisites, минимальная и полная конфигурация, проверка, troubleshooting.

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

  • OpenTelemetry SDK в приложении, поддерживающий OTLP/HTTP с JSON-кодированием (Protobuf не поддерживается ни в одном из режимов).
  • Токен workspace из дашборда — ${FLAREE_TOKEN} для agentless и в agent.yaml для loopback-режима.
  • Для режима «через агент»: агент Flaree ≥ 1.0 на том же хосте, что и приложение; сетевая доступность loopback 127.0.0.1:4318 из приложения (для контейнера — network_mode: host или общий pod).
  • Для режима «прямой ingestion»: исходящий HTTPS до api.flaree.ru:443 из приложения и любая среда, способная отправить HTTP-запрос с Content-Type: application/json и заголовком авторизации.

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

Через агент (loopback)​

agent.yaml:

otlp:
  enabled: true
  host: 127.0.0.1
  port: 4318

Приложение отправляет сигналы на http://127.0.0.1:4318/v1/logs, /v1/metrics, /v1/traces. Приёмник отказывается стартовать с host: 0.0.0.0 — это защищает поверхность агента от публичного доступа.

Конфиг OTEL SDK в приложении (через переменные окружения):

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

Прямой ingestion (agentless)​

Агент не нужен. OTEL SDK в приложении бьёт прямо в публичный шлюз с токеном workspace в заголовке:

OTEL_EXPORTER_OTLP_PROTOCOL=http/json
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.flaree.ru/otlp
OTEL_EXPORTER_OTLP_HEADERS=x-flaree-token=${FLAREE_TOKEN}

SDK сам подставит /v1/logs, /v1/metrics, /v1/traces к корню endpoint.

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

Через агент (loopback)​

otlp:
  enabled: true
  host: 127.0.0.1
  port: 4318
  signals:
    logs: true
    metrics: true
    traces: true
  max_payload_bytes: 4194304
  redact_fields:
    - http.request.header.authorization
    - db.statement
    - user.email
  headers_required:
    x-agent-token: ${FLAREE_TOKEN}

Поля:

  • signals — включает конкретные типы сигналов (по умолчанию все три).
  • max_payload_bytes — верхняя граница тела запроса; превышение возвращает 413 payload_too_large без потери ранее принятых батчей.
  • redact_fields — маскировка секрет-атрибутов на агенте до отправки на backend; в agentless-режиме недоступна — приложение должно делать redact самостоятельно.
  • headers_required — опциональный pre-shared-ключ между приложением и агентом; секрет берётся из ${FLAREE_*}-переменной.

Прямой ingestion (agentless)​

OpenTelemetry Collector — наиболее удобный путь, если сигналы от нескольких источников нужно собрать в один поток до отправки во Flaree:

# otel-collector.yaml
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 1000
  attributes/redact:
    actions:
      - key: http.request.header.authorization
        action: delete
      - key: db.statement
        action: delete

exporters:
  otlphttp/flaree:
    endpoint: https://api.flaree.ru/otlp
    encoding: json
    headers:
      x-flaree-token: ${FLAREE_TOKEN}
    compression: gzip
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch, attributes/redact]
      exporters: [otlphttp/flaree]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/flaree]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/flaree]

В agentless-режиме backend возвращает HTTP 429 при превышении квоты — клиент должен уважать заголовок Retry-After и поле reset_at в теле ответа (детали — в Reference: API).

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

  1. Отправьте пустой batch логов на свой endpoint и убедитесь, что приёмник отвечает HTTP 200 (или 204).
  2. Убедитесь, что счётчик flaree_agent_otlp_accepted_total (loopback-режим) или метрика клиента OTEL Collector otelcol_exporter_sent_log_records (agentless-режим) растёт после каждого батча.
  3. Проверьте, что сигналы доходят до облака: в дашборде app.flaree.ru у соответствующего компонента появляются свежие логи или метрики в течение ≤ 1 минуты.
# Через агент (loopback)
curl -sS http://127.0.0.1:4318/v1/logs \
  -H 'Content-Type: application/json' \
  -d '{}' -o /dev/null -w '%{http_code}\n'
curl -sS http://127.0.0.1:9100/metrics | grep flaree_agent_otlp_accepted_total

# Прямой ingestion (agentless)
curl -sS https://api.flaree.ru/otlp/v1/logs \
  -H 'Content-Type: application/json' \
  -H "x-flaree-token: ${FLAREE_TOKEN}" \
  -d '{}' -o /dev/null -w '%{http_code}\n'

Troubleshooting​

tip

В loopback-режиме на VM проверьте, что firewall не режет loopback-трафик и что 127.0.0.1:4318 не занят посторонним сервисом (ss -lnt 'sport = :4318'). В agentless — что у среды есть исходящий HTTPS до api.flaree.ru:443.