ОтелGrpcТранспорт
gRPC-транспорт для отправки телеметрии по протоколу OTLP.
Описание
Обеспечивает отправку данных трассировки, метрик и логов через gRPC на адреса OTLP-совместимых коллекторов (Grafana LGTM, OpenTelemetry Collector и т.д.). Использует библиотеку oint (OPI_GRPC) для gRPC-вызовов.
Реализует тот же интерфейс Отправить(Путь, Данные, ТаймаутМс), что и ОтелHttpТранспорт, поэтому все существующие экспортеры (спаны, логи, метрики) работают с обоими транспортами.
Данные передаются в формате OTLP JSON (camelCase ключи); транспорт автоматически конвертирует их в формат protobuf (snake_case ключи) через внутренний конвертер.
Временные ошибки повторяются с экспоненциальной задержкой и jitter. По спецификации OTLP/gRPC это коды CANCELLED, DEADLINE_EXCEEDED, ABORTED, OUT_OF_RANGE, UNAVAILABLE, DATA_LOSS, а RESOURCE_EXHAUSTED — только если сервер вернул RetryInfo. Код распознаётся в обеих записях: DeadlineExceeded (так его пишет клиент tonic в OPI_GRPC) и DEADLINE_EXCEEDED.
Если сервер прислал в деталях статуса RetryInfo (OTLP/gRPC Throttling), первый повтор идёт не раньше retry_delay, а каждый следующий ждёт вдвое дольше. Если retry_delay не меньше времени, оставшегося до срока отправки, повтор в срок не уложится: отправка прекращается сразу, ошибка пишется в лог. Детали статуса транспорт берёт из текста ошибки OPI_GRPC: клиент tonic пишет в него сериализованный google.rpc.Status списком байтов (details: [8, 14, ...]).
Защищённость соединения задаёт схема адреса: https:// — соединение с TLS, http:// — без TLS. По TLS сертификат сервера проверяется всегда: по системным и встроенным корневым сертификатам и по ФайлСертификата из настроек TLS (собственный CA коллектора). Адрес без схемы защищён TLS, если в настройках TLS не включён Insecure; с Insecure = Истина соединение идёт без TLS. Схема важнее Insecure: Insecure не отключает TLS для https:// и не включает его для http://.
Если коллектор недоступен при создании транспорта, соединение открывается заново при отправке (с теми же повторами); после Закрыть() соединение больше не открывается. Ошибки компоненты OPI_GRPC при открытии соединения записываются в лог и не выбрасываются из конструктора.
Транспорт добавляет в метаданные вызова user-agent со стандартной строкой OTel-OTLP-Exporter-OneScript/<версия>. Пользовательские метаданные user-agent (в любом регистре) — идентификатор продукта: он ставится перед стандартной строкой, например MyDistribution/1.2.3 OTel-OTLP-Exporter-OneScript/1.1.0. До сервера метаданные user-agent пока не доходят — см. ограничения ниже.
Ограничения клиента OPI_GRPC:
- сжатие (
gzip) не поддерживается, данные отправляются без сжатия (OpenIntegrations#112); - mTLS (клиентский ключ и сертификат) не поддерживается (OpenIntegrations#102);
- максимальный размер ответа фиксирован клиентом gRPC — 4 MiB (значение по умолчанию спецификации), настроить его нельзя (OpenIntegrations#113);
- заголовок
user-agentзадаёт сам клиент tonic внутри OPI_GRPC: метаданныеuser-agentдо сервера не доходят, сервер получаетtonic/0.13.1. User-Agent в tonic задаётся только при создании gRPC-канала (Endpoint::user_agent), а такой настройки OPI_GRPC пока не даёт (OpenIntegrations#111); - таймаута подключения нет: открытие соединения (в конструкторе и при отправке) и переподключение внутри вызова сроком отправки не ограничены. Сервер, который принял TCP-соединение и молчит (TLS-рукопожатие не завершается), держит конструктор или отправку, пока сам не закроет соединение; адрес, который не отвечает на TCP-подключение, — до системного таймаута подключения (в Linux около 2 минут). Пока это не исправлено, экспорт по gRPC может блокироваться дольше срока: требования спецификации «Export MUST NOT block indefinitely» и «Shutdown/ForceFlush SHOULD complete or abort within some timeout» для gRPC выполняются не полностью (OpenIntegrations#114).
Конструктор
Новый ОтелGrpcТранспорт(
Адрес,
НастройкиTls,
Метаданные,
КаталогProto,
Таймаут,
НовыйМаксПопыток
)| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Адрес | Строка | — | Адрес OTLP-коллектора, например "http://localhost:4317". https:// — соединение с TLS, http:// — без TLS; адрес без схемы защищён TLS, если не включён Insecure |
НастройкиTls | ОтелНастройкиTls | Неопределено | Настройки TLS: ФайлСертификата — собственный CA для проверки сервера, Insecure — адрес без схемы без TLS |
Метаданные | Соответствие | Неопределено | Метаданные gRPC, отправляемые с каждым вызовом |
КаталогProto | Строка | "" | Каталог с OTLP .proto файлами (по умолчанию proto/ рядом с библиотекой) |
Таймаут | Число | 10000 | Таймаут gRPC-вызова в миллисекундах |
НовыйМаксПопыток | Число | 3 | Максимальное количество попыток отправки |
Методы
Отправить
Отправляет данные на указанный путь OTLP-адреса через gRPC в пределах срока. Автоматически конвертирует OTLP JSON в формат protobuf.
Отправка идёт в вызывающем потоке, все попытки и паузы между ними укладываются в срок: таймаут вызова не больше времени, оставшегося до срока, после срока новая попытка не начинается, а пауза прерывается. Открытие соединения и переподключение в срок не укладываются — см. ограничения OPI_GRPC выше (OpenIntegrations#114).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Путь | Строка | — | Путь OTLP-адреса, например "/v1/traces" |
Данные | Соответствие | — | Данные для отправки в формате OTLP JSON |
ТаймаутМс | Число | 0 | Срок отправки в миллисекундах, 0 — без ограничения |
Возвращает: Булево — Истина, если отправка прошла успешно
Закрыть
Закрывает gRPC-соединение. После вызова транспорт перестаёт принимать запросы и не открывает соединение заново. Повторный вызов ничего не делает.
Транспорт, созданный автоконфигурацией, закрывает экспортер при закрытии SDK. Транспорт, который пользователь передал экспортеру, пользователь закрывает сам: один транспорт может обслуживать экспортеры всех трёх сигналов.
МаксРазмерЗапроса
Возвращает максимальный размер запроса в байтах. Размер считается до сжатия, запрос больше лимита не отправляется (ошибка в логе, Отправить возвращает Ложь).
Возвращает: Число — по умолчанию 67108864 (64 MiB); 0 — без ограничения
УстановитьМаксРазмерЗапроса
Устанавливает максимальный размер запроса в байтах.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Значение | Число | — | Максимальный размер запроса в байтах; 0 — без ограничения |
Возвращает: ОтелGrpcТранспорт — этот транспорт
Адрес
Возвращает адрес коллектора, с которым соединяется транспорт. Адресу без схемы транспорт задаёт схему по Insecure.
Возвращает: Строка — адрес со схемой: https:// — соединение с TLS, http:// — без TLS
ПолучитьМетаданные
Возвращает метаданные gRPC, отправляемые с каждым вызовом.
Возвращает: Соответствие — метаданные gRPC
ПолучитьНастройкиTls
Возвращает настройки TLS транспорта.
Возвращает: ОтелНастройкиTls, Неопределено — настройки TLS или Неопределено, если не заданы
Внутренние методы
Экспортированы для служебных вызовов (в OneScript нет внутренней видимости): ВыполнитьОднуПопытку и РассчитатьЗадержкуRetryInfo через Действие вызывает стратегия повтора библиотеки resilience в Отправить, остальные — сам транспорт и модульные тесты. Приложению вызывать их не нужно:
ВыполнитьОднуПопытку— одна попытка gRPC-вызова, которую повторяетОтправить: при необходимости открывает соединение, ограничивает вызов временем до срока; успешный ответ —Истина; повторяемая ошибка или недоступный коллектор — исключение, чтобы стратегия повторила вызов (сretry_delay, если сервер прислал RetryInfo); неповторяемая ошибка, закрытый транспорт илиretry_delayне раньше срока —Ложь;ОшибкаПовторяемая— определяет по тексту ошибки OPI_GRPC, повторять ли вызов: кодыCANCELLED,DEADLINE_EXCEEDED,ABORTED,OUT_OF_RANGE,UNAVAILABLE,DATA_LOSS, аRESOURCE_EXHAUSTED— только с RetryInfo;ЗадержкаRetryInfo—retry_delayиз RetryInfo в деталях статуса (текст ошибки OPI_GRPC) в миллисекундах;Неопределено, если RetryInfo нет;РассчитатьЗадержкуRetryInfo— задержка перед повтором для стратегии повтора:retry_delay, удвоенная за каждую следующую попытку;Неопределено, если RetryInfo с задержкой нет (действует экспоненциальная задержка стратегии).
Пример
#Использовать opentelemetry
// Простой gRPC-транспорт
Транспорт = Новый ОтелGrpcТранспорт("http://localhost:4317");
// С метаданными авторизации
Метаданные = Новый Соответствие();
Метаданные.Вставить("authorization", "Bearer mytoken");
Транспорт = Новый ОтелGrpcТранспорт("http://localhost:4317", , Метаданные);
// С TLS и собственным CA коллектора
НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.ФайлСертификата = "/etc/ssl/ca.crt";
Транспорт = Новый ОтелGrpcТранспорт("https://collector.example.com", НастройкиTls);
// Адрес без схемы: без Insecure соединение защищено TLS, с Insecure - без TLS
НастройкиTls = Новый ОтелНастройкиTls();
НастройкиTls.Insecure = Истина;
Транспорт = Новый ОтелGrpcТранспорт("collector:4317", НастройкиTls);
// Использование с экспортером
ЭкспортерСпанов = Новый ОтелЭкспортерСпанов(Транспорт);
// Транспорт создан пользователем: после закрытия SDK закрыть соединение
Транспорт.Закрыть();