ОтелУтилиты

Модуль вспомогательных функций SDK: время в формате OpenTelemetry, часы, генератор идентификаторов и тип ошибки для exception.type и error.type, общий для SDK и библиотек инструментирования.

Описание

Время в API библиотеки — строка с числом наносекунд от начала эпохи Unix (1970-01-01 00:00:00 UTC), например "1700000000500000000". В этих единицах метки времени передаёт OTLP. Спецификация допускает точность от миллисекунд до наносекунд: время, которое SDK ставит само, имеет точность до миллисекунд (последние шесть цифр — нули), а время из внешнего источника с большей точностью передаётся без потерь.

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

• текущее время — ТекущееВремяВНаносекундах();
• время, засечённое через ТекущаяУниверсальнаяДатаВМиллисекундах(), — МиллисекундыВНаносекунды().

Часы и генератор идентификаторов модуля общие для всего SDK в процессе. Генератор у конкретного провайдера трассировки задаёт ОтелПостроительПровайдераТрассировки.УстановитьГенераторИд.

Функции

ТекущееВремяВНаносекундах

Возвращает текущее время. Если установлены свои часы (см. УстановитьЧасы), время берётся из них.

Возвращает: Строка — наносекунды от начала эпохи Unix

---

МиллисекундыВНаносекунды

Переводит время из миллисекунд от 0001-01-01 UTC — формата ТекущаяУниверсальнаяДатаВМиллисекундах() и библиотеки logos — в наносекунды от начала эпохи Unix.

Параметр	Тип	По умолчанию	Описание
МиллисекундыОт0001	Число	—	Целое число миллисекунд от 0001-01-01 UTC

Возвращает: Строка — наносекунды от начала эпохи Unix

---

УстановитьЧасы

Устанавливает свои часы (аналог Java SDK: SdkTracerProviderBuilder.setClock). Часы — объект с функцией ТекущееВремяВНаносекундах(), которая возвращает строку наносекунд от начала эпохи Unix. Часы общие для всего SDK: из них берётся всё время, которое SDK ставит само, — начало и окончание спанов, время событий, записей логов, точек метрик и exemplars.

Параметр	Тип	По умолчанию	Описание
Значение	Произвольный	—	Объект с функцией ТекущееВремяВНаносекундах()

---

СброситьЧасы

Возвращает системные часы.

---

УстановитьГенераторИд

Устанавливает генератор идентификаторов для провайдеров трассировки, у которых свой генератор не задан. Генератор — объект с функциями СгенерироватьИдТрассировки() (32 hex-символа) и СгенерироватьИдСпана() (16 hex-символов). Идентификатор должен быть строчной hex-строкой нужной длины не из одних нулей; некорректный идентификатор пишется в лог как ошибка и заменяется идентификатором генератора по умолчанию (на основе УникальныйИдентификатор).

Параметр	Тип	По умолчанию	Описание
Генератор	Произвольный	—	Объект с функциями СгенерироватьИдТрассировки() и СгенерироватьИдСпана()

---

СброситьГенераторИд

Возвращает генератор идентификаторов по умолчанию.

---

УстановитьКлассификаторНативныхОшибок

Устанавливает свой классификатор ошибок без кода библиотеки errors, по которому ЗаписатьИсключение спана и запись лога заполняют exception.type. Классификатор — объект с функцией Классифицировать(ИнформацияОбОшибке), которая, как КлассификаторОшибок библиотеки errors, возвращает ошибку с кодом или Неопределено. Классификатор общий для всего SDK; по умолчанию — классификатор с правилами native-errors, созданный при загрузке модуля. Исключение классификатора SDK не пробрасывает: тип остаётся незаполненным.

Параметр	Тип	По умолчанию	Описание
Значение	Произвольный	—	Объект с функцией Классифицировать(ИнформацияОбОшибке)

---

СброситьКлассификаторНативныхОшибок

Возвращает классификатор нативных ошибок OneScript по умолчанию.

---

ТипИсключения

Возвращает значение exception.type — тот же тип, что ставят ЗаписатьИсключение спана и запись лога: код ошибки библиотеки errors, а у ошибки без кода — код классификатора нативных ошибок (numeric.division_by_zero, network.connection.refused и т.п.). Нужен библиотекам инструментирования, которые получают тип один раз и передают его явно: exception.type в ДополнительныеАтрибуты спана не запускает повторную классификацию.

Параметр	Тип	По умолчанию	Описание
ИнформацияОбИсключении	ИнформацияОбОшибке	—	Информация об исключении

Возвращает: Строка, Неопределено — код ошибки; Неопределено, если ошибка не распознана или передана не ИнформацияОбОшибке

---

ТипОшибки

Возвращает значение error.type для операции, завершившейся исключением: тип исключения (см. ТипИсключения), а если он не определён — _OTHER (ОтелСемантическиеСоглашения.ТипОшибкиДругой()), запасное значение семантических соглашений. Библиотеки инструментирования берут тип отсюда, чтобы error.type в спанах и метриках был одинаков.

Параметр	Тип	По умолчанию	Описание
ИнформацияОбИсключении	ИнформацияОбОшибке	—	Информация об исключении

Возвращает: Строка — тип ошибки

Исключение
    Ошибка = ИнформацияОбОшибке();
    Тип = ОтелУтилиты.ТипИсключения(Ошибка);
    Доп = Новый ОтелАтрибуты();
    Если Тип <> Неопределено Тогда
        Доп.Установить("exception.type", Тип);
    КонецЕсли;
    Спан.ЗаписатьИсключение(Ошибка, Доп);
    // Тот же тип без повторной классификации
    Спан.УстановитьАтрибут(ОтелСемантическиеСоглашения.ТипОшибки(),
        ?(Тип = Неопределено, ОтелСемантическиеСоглашения.ТипОшибкиДругой(), Тип));
КонецПопытки;

---

СтекВызововИсключения

Возвращает значение exception.stacktrace: описание ошибки и кадры стека OneScript, затем цепочку причин — описание каждой причины после Caused by: и её кадры. Этот формат пишут событие исключения спана (ОтелСпан.ЗаписатьИсключение) и запись лога (ОтелЗаписьЛога.УстановитьИсключение), так что стек одной ошибки в трассах и логах одинаков. Кадров движка .NET из ПодробноеОписаниеОшибки() в нём нет. У объекта без стека вызовов и причин — только описание.

Параметр	Тип	По умолчанию	Описание
ИнформацияОбИсключении	ИнформацияОбОшибке	—	Информация об исключении

Возвращает: Строка — стек вызовов

app.calc.failed: Расчет не удался
  /app/Расчет.os / Метод Рассчитать / Строка 12
Caused by: Деление на ноль
  /app/Расчет.os / Метод Разделить / Строка 3
  /app/Расчет.os / Метод Рассчитать / Строка 10

Внутренние функции

Экспортированы только для вызова из других модулей SDK (в OneScript нет внутренней видимости), приложению вызывать их не нужно:

• СгенерироватьИдТрассировки, СгенерироватьИдСпана — идентификаторы для провайдера трассировки;
• ВШестнадцатеричнуюСтроку, ИзШестнадцатеричнойСтроки, ЯвляетсяШестнадцатеричнойСтрокой, ЯвляетсяШестнадцатеричнойСтрокойВНижнемРегистре, ЯвляетсяВалиднымИдентификатором — разбор и проверка hex-значений для пропагаторов и сэмплера;
• РаскодироватьURLСтрого — разбор percent-encoding в атрибутах ресурса из окружения;
• ЗначениеАтрибутаВФорматОтел, ОграничитьЗначениеАтрибута — перевод значения атрибута в OTLP и лимиты длины и глубины;
• ВерсияSDK, ВерсияПакета, UserAgentЭкспортераOtlp — версия SDK для ресурса и User-Agent экспортера;
• РесурсДетектора — ресурс детекторов хоста, процесса и процессора;
• ИдЭкземпляраСервиса — service.instance.id процесса для детектора экземпляра сервиса.

Функции Транслитерировать (кириллица в латиницу в нижнем регистре) и ПроверитьИмяМетрики (исключение, если имя не из символов a-z, A-Z, 0-9, _, ., - или начинается не с буквы) SDK не вызывает: имя инструмента проверяет метр по правилам спецификации.

Пример

// Операция уже прошла: время начала и окончания засечены заранее
Начало = ТекущаяУниверсальнаяДатаВМиллисекундах();
// ... операция ...
Окончание = ТекущаяУниверсальнаяДатаВМиллисекундах();

Спан = Трассировщик.НачатьСпан("Загрузка", , , , ОтелУтилиты.МиллисекундыВНаносекунды(Начало));
Спан.Завершить(ОтелУтилиты.МиллисекундыВНаносекунды(Окончание));

См. также

• ОтелСпан
• ОтелТрассировщик
• ОтелЗаписьЛога