ОтелHttpТранспорт

HTTP-транспорт для отправки телеметрии по протоколу OTLP.

Описание

Обеспечивает отправку данных трассировки, метрик и логов в формате JSON или protobuf по HTTP на адреса OTLP-совместимых коллекторов (Grafana LGTM, OpenTelemetry Collector и т.д.). Использует библиотеку 1connector для HTTP-запросов.

При получении HTTP-кодов 429, 502, 503, 504 и при ошибке соединения транспорт повторяет попытку с экспоненциальной задержкой и jitter или с паузой из Retry-After. Попытки и паузы укладываются в срок отправки, который передаёт экспортёр (см. Отправить).

Поддерживает протоколы http/protobuf (по умолчанию, согласно спецификации OTel) и http/json, gzip-сжатие тела запроса, а также TLS-настройки через ОтелНастройкиTls.

Запрос больше максимального размера (по умолчанию 64 MiB, размер до сжатия) не отправляется, ответ больше максимального размера (по умолчанию 4 MiB) не принимается — в обоих случаях ошибка пишется в лог, а Отправить возвращает Ложь.

Пользовательский заголовок User-Agent (в любом регистре) — идентификатор продукта: он добавляется перед стандартным OTel-OTLP-Exporter-OneScript/<версия>, например MyDistribution/1.2.3 OTel-OTLP-Exporter-OneScript/1.1.0.

HTTP-клиент OneScript не применяет файлы сертификатов (ФайлСертификата, ФайлКлиентскогоКлюча, ФайлКлиентскогоСертификата): транспорт предупреждает об этом при создании. Insecure по спецификации относится только к gRPC: защищённость HTTP-соединения задаёт схема адреса.

Безопасность. HTTP-клиент OneScript (HTTPСоединение, через него работает 1connector) не проверяет сертификат сервера по HTTPS: соединение шифруется, но принимается любой сертификат, в том числе самоподписанный или выданный на другое имя. Подлинность коллектора не подтверждается, и телеметрию получит любой сервер, перехвативший соединение. Если это важно, используйте ОтелGrpcТранспорт — он проверяет сертификат сервера, — или доверенную сеть до коллектора.

Конструктор

Новый ОтелHttpТранспорт(
    Адрес,
    НовыеЗаголовки,
    Таймаут,
    НовыйМаксПопыток,
    Компрессия,
    НастройкиTls,
    НовыйПротокол,
    НовыйСигнал
)

Параметр	Тип	По умолчанию	Описание
Адрес	Строка	—	Адрес OTLP-коллектора, например "http://localhost:4318"
НовыеЗаголовки	Соответствие	Неопределено	Дополнительные HTTP-заголовки, отправляемые с каждым запросом
Таймаут	Число	10	Таймаут HTTP-запроса в секундах, 0 — без ограничения
НовыйМаксПопыток	Число	3	Максимальное количество попыток отправки при повторяемых ошибках
Компрессия	Строка	Неопределено	Алгоритм сжатия: "gzip" или Неопределено для отключения
НастройкиTls	ОтелНастройкиTls	Неопределено	Настройки TLS для защищённых соединений
НовыйПротокол	Строка	"http/protobuf"	Протокол OTLP: "http/protobuf" или "http/json"
НовыйСигнал	Строка	""	Сигнал телеметрии: "traces", "metrics", "logs" или пустая строка

Методы

Отправить

Отправляет данные на указанный путь OTLP-адреса в пределах срока. При получении HTTP 429/502/503/504 и при ошибке соединения повторяет попытку с экспоненциальной задержкой или с паузой из Retry-After. Поддерживает оба протокола: http/json и http/protobuf.

Retry-After — число секунд или дата HTTP в любом из трёх форматов RFC 7231: IMF-fixdate (Sun, 06 Nov 1994 08:49:37 GMT), RFC 850 (Sunday, 06-Nov-94 08:49:37 GMT) и asctime (Sun Nov 6 08:49:37 1994). Прошедшая дата не задерживает повтор.

Отправка идёт в вызывающем потоке, все попытки и паузы между ними укладываются в срок: таймаут запроса не больше времени, оставшегося до срока, после срока новая попытка не начинается, а пауза прерывается.

Параметр	Тип	По умолчанию	Описание
Путь	Строка	—	Путь OTLP-адреса, например "/v1/traces"
Данные	Соответствие	—	Данные для отправки в формате OTLP JSON
ТаймаутМс	Число	0	Срок отправки в миллисекундах, 0 — без ограничения

Возвращает: Булево — Истина, если отправка прошла успешно; Ложь при ошибке и после Закрыть

Ограничения HTTP-клиента OneScript:

• таймаут запроса задаётся в секундах, поэтому время до срока округляется вверх до секунды и отправка может закончиться позже срока меньше чем на секунду;
• таймаут ограничивает соединение и ожидание заголовков ответа, но не чтение тела: если сервер отправил заголовки и перестал отвечать, тело ждёт около 5 минут при любом сроке (EvilBeaver/OneScript#1789).

Если сервер разрешает повтор (Retry-After) только после срока, повторить в срок нельзя: транспорт сразу возвращает Ложь и пишет ошибку в лог. Экспоненциальная пауза, которая не успевает закончиться до срока, прерывается на сроке.

Закрыть

Закрывает транспорт: после вызова Отправить возвращает Ложь и пишет ошибку в лог. Соединений между запросами HTTP-транспорт не держит (каждая отправка — отдельный запрос), поэтому освобождать нечего. Повторный вызов ничего не делает.

Транспорт, созданный автоконфигурацией или по файлу конфигурации, закрывает экспортер при закрытии SDK. Транспорт, который пользователь передал экспортеру, пользователь закрывает сам.

ПолучитьЗаголовки

Возвращает HTTP-заголовки, отправляемые с каждым запросом.

Возвращает: Соответствие — заголовки HTTP-запроса

Таймаут

Возвращает таймаут HTTP-запроса в секундах. Заданный 0 (без ограничения) возвращается как 2147483 (2^31-1 мс): библиотека 1connector считает 0 незаданным и ограничивает запрос 30 с, поэтому транспорт передаёт ей очень большой срок, как допускает спецификация.

Возвращает: Число — таймаут в секундах

ПолучитьНастройкиTls

Возвращает настройки TLS транспорта.

Возвращает: ОтелНастройкиTls, Неопределено — настройки TLS или Неопределено, если не заданы

МаксРазмерЗапроса / УстановитьМаксРазмерЗапроса

Максимальный размер запроса в байтах до сжатия (Max Request Size); 0 — без ограничения. Установщик возвращает ОтелHttpТранспорт для цепочки вызовов.

Возвращает: Число — по умолчанию 67108864 (64 MiB)

МаксРазмерОтвета / УстановитьМаксРазмерОтвета

Максимальный размер принимаемого ответа в байтах (Max Response Size). Установщик возвращает ОтелHttpТранспорт для цепочки вызовов.

Возвращает: Число — по умолчанию 4194304 (4 MiB)

Внутренние методы

Экспортированы для служебных вызовов (в OneScript нет внутренней видимости): их через Действие вызывает стратегия повтора библиотеки resilience в Отправить. Приложению вызывать их не нужно:

• ВыполнитьОднуПопытку — одна попытка HTTP-запроса, которую повторяет Отправить: таймаут запроса не больше таймаута транспорта и времени до срока, округлённого вверх до секунды; код 2xx — Истина; коды 429, 502, 503, 504 — исключение с задержкой из Retry-After, чтобы стратегия повторила запрос, а если Retry-After разрешает повтор не раньше срока — Ложь; другой код или ответ больше максимального размера — Ложь; ошибка соединения выходит исключением и тоже повторяется;
• РассчитатьЗадержкуRetryAfter — задержка перед повтором для стратегии повтора: пауза из Retry-After в миллисекундах; Неопределено, если заголовка нет или пауза нулевая (действует экспоненциальная задержка стратегии).

Пример

#Использовать opentelemetry

// Простой HTTP-транспорт
Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");

// С заголовками авторизации и gzip-сжатием
Заголовки = Новый Соответствие();
Заголовки.Вставить("Authorization", "Bearer mytoken");
Транспорт = Новый ОтелHttpТранспорт("https://collector.example.com", Заголовки, 30, 5, "gzip");

// С идентификатором дистрибутива в User-Agent и лимитом размера запроса 16 MiB
Заголовки = Новый Соответствие();
Заголовки.Вставить("User-Agent", "MyDistribution/1.2.3");
Транспорт = Новый ОтелHttpТранспорт("https://collector.example.com", Заголовки)
    .УстановитьМаксРазмерЗапроса(16777216);

// Использование с экспортером спанов
ЭкспортерСпанов = Новый ОтелЭкспортерСпанов(Транспорт);