ОтелТрассировщик
Трассировщик — потокобезопасный объект для создания и управления спанами.
Описание
Все публичные методы безопасны для параллельного вызова из нескольких потоков. Создаётся через ОтелПровайдерТрассировки.ПолучитьТрассировщик() или ОтелSdk.ПолучитьТрассировщик(). Аналог Java SDK: Tracer.
Методы
ПостроительСпана
Создает построитель спана (SpanBuilder).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ИмяСпана | Строка | — | Имя спана |
Возвращает: ОтелПостроительСпана
Включен
Проверяет, включён ли трассировщик. Возвращает Ложь, если у провайдера нет зарегистрированных процессоров спанов, а также в API-режиме (SDK не сконфигурирован или провайдер закрыт).
Режим создания спанов от результата не зависит:
- SDK-режим: IdGenerator + Sampler работают штатно, создаются реальные спаны — в том числе без процессоров.
- API-режим: возвращается non-recording Span, IdGenerator не вызывается.
По спецификации: инструментирующий код SHOULD вызывать
Включен()непосредственно перед каждым созданием спана, не кэшируя результат надолго.
Возвращает: Булево — Истина, если трассировщик может обрабатывать спаны
НачатьСпан
Начинает новый спан. Если в контексте есть текущий спан с валидным контекстом, создаёт дочерний; иначе — корневой с новым TraceId. Невалидный спан в контексте (нулевые ID, например ОтелСпаны.Невалидный()) родителем не считается.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ИмяСпана | Строка | — | Имя спана |
ВидСпана | Число | Неопределено | Вид спана из ОтелВидСпана |
НачальныеАтрибуты | Соответствие | Неопределено | Начальные атрибуты, передаются сэмплеру |
Линки | Массив из ОтелЛинк | Неопределено | Начальные линки |
ВремяНачала | Строка | Неопределено | Время начала в наносекундах (Unix epoch), процессоры видят его уже в ПриНачале; по умолчанию текущее время |
Возвращает: ОтелСпан, ОтелНезаписывающийСпан — спан или незаписывающий спан, если отброшен семплером. ОтелНезаписывающийСпан — служебный класс, напрямую не создаётся
НачатьКорневойСпан
Начинает новый корневой спан (без родителя). Текущий спан родителем не становится: сэмплер и процессоры (в ПриНачале) получают текущий контекст, в котором спан заменён невалидным, — остальные значения контекста, например Baggage, сохраняются.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ИмяСпана | Строка | — | Имя спана |
ВидСпана | Число | Неопределено | Вид спана из ОтелВидСпана |
НачальныеАтрибуты | Соответствие | Неопределено | Начальные атрибуты |
Линки | Массив из ОтелЛинк | Неопределено | Начальные линки |
ВремяНачала | Строка | Неопределено | Время начала в наносекундах; по умолчанию текущее время |
Возвращает: ОтелСпан, ОтелНезаписывающийСпан
НачатьДочернийСпан
Начинает новый спан с родителем из переданного контекста (Context): спан из контекста становится родителем, контекст без спана даёт корневой спан. Спан передаётся в контексте через ОтелКонтекст.КонтекстСоСпаном; если известен только контекст спана, его оборачивают в спан функцией ОтелСпаны.Обернуть. Если спан в контексте невалиден (нулевые ID), создаётся корневой спан с новым TraceId. Контекст передаётся процессорам в ПриНачале.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
ИмяСпана | Строка | — | Имя спана |
РодительскийКонтекст | ФиксированноеСоответствие, Соответствие | — | Контекст (Context) родителя |
ВидСпана | Число | Неопределено | Вид спана из ОтелВидСпана |
НачальныеАтрибуты | Соответствие | Неопределено | Начальные атрибуты |
Линки | Массив из ОтелЛинк | Неопределено | Начальные линки |
ВремяНачала | Строка | Неопределено | Время начала в наносекундах; по умолчанию текущее время |
Возвращает: ОтелСпан, ОтелНезаписывающийСпан
ОбластьИнструментирования
Возвращает область инструментирования трассировщика.
Возвращает: ОтелОбластьИнструментирования
Внутренние методы
Экспортированы только для вызова из других модулей SDK (в OneScript нет внутренней видимости), приложению вызывать их не нужно:
НачатьСпанВКонтексте— начинает спан с родителем из переданного контекста (Context): общая реализацияНачатьСпан,НачатьДочернийСпаниНачатьСпанпостроителя спана с заданным родителем. Приложение вызываетНачатьДочернийСпан— параметры и поведение у него те же.
Пример
Трассировщик = Сдк.ПолучитьТрассировщик("мой-сервис", "1.0.0");
Спан = Трассировщик.ПостроительСпана("обработка-запроса")
.УстановитьВидСпана(ОтелВидСпана.Сервер())
.УстановитьАтрибут("http.method", "GET")
.НачатьСпан();
Токен = Спан.СделатьТекущим();
Попытка
// ... логика обработки ...
Исключение
Спан.ЗаписатьИсключение(ИнформацияОбОшибке());
Спан.УстановитьСтатус(ОтелКодСтатуса.Ошибка());
КонецПопытки;
Токен.Закрыть();
Спан.Завершить();