ОтелСпан

Спан трассировки (Span).

Описание

Потокобезопасный объект, содержащий данные одной единицы работы. Создаётся через Трассировщик.НачатьСпан(), НачатьКорневойСпан(), НачатьДочернийСпан() или ОтелПостроительСпана.НачатьСпан().

Важно: Конструктор технически публичен из-за ограничений OneScript, но НЕ должен вызываться напрямую. Используйте только методы трассировщика.

Все методы записи (установка статуса, атрибутов и т.д.) не производят действий, если спан уже завершён.

Время спана и его событий — строка с числом наносекунд от начала эпохи Unix, как в OTLP, например "1700000000500000000". Время, которое SDK ставит само, имеет точность до миллисекунд. Строку для своего времени дают функции ОтелУтилиты.

Методы чтения

Имя

Возвращает имя спана.

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

---

КонтекстСпана

Возвращает неизменяемый контекст спана (SpanContext).

Возвращает: ОтелКонтекстСпана

---

ИдРодительскогоСпана

Возвращает идентификатор родительского спана.

Возвращает: Строка — 16 hex-символов или пустая строка для корневого спана

---

КонтекстРодительскогоСпана

Возвращает контекст спана родителя.

Возвращает: ОтелКонтекстСпана

---

ВидСпана

Возвращает вид спана.

Возвращает: Число — константа из ОтелВидСпана

---

ВремяНачала

Возвращает время начала спана.

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

---

ВремяОкончания

Возвращает время окончания спана.

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

---

Атрибуты

Возвращает копию атрибутов спана. Изменение копии не меняет спан: атрибуты записываются только через УстановитьАтрибут, который применяет лимиты ОтелЛимитыСпана.

Возвращает: ОтелАтрибуты

---

События

Возвращает копию списка событий спана: изменение копии спан не меняет.

Возвращает: Массив из ОтелСобытиеСпана

---

Линки

Возвращает копию списка линков спана: изменение копии спан не меняет.

Возвращает: Массив из ОтелЛинк

---

Ресурс

Возвращает ресурс спана (из провайдера трассировки).

Возвращает: ОтелРесурс

---

ОбластьИнструментирования

Возвращает область инструментирования (InstrumentationScope).

Возвращает: ОтелОбластьИнструментирования

---

БиблиотекаИнструментирования

Устаревший синоним ОбластьИнструментирования (прежнее имя в спецификации — InstrumentationLibrary). Используйте ОбластьИнструментирования.

Возвращает: ОтелОбластьИнструментирования

---

КодСтатуса

Возвращает код статуса спана.

Возвращает: Число — константа из ОтелКодСтатуса

---

СообщениеСтатуса

Возвращает сообщение статуса.

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

---

Завершен

Проверяет, завершён ли спан.

Возвращает: Булево

---

ЗаписьАктивна

Проверяет, записывает ли спан данные (IsRecording): Истина до вызова Завершить, Ложь после. У незаписывающего спана (ОтелНезаписывающийСпан) всегда Ложь.

Возвращает: Булево

---

КоличествоОтброшенныхАтрибутов

Возвращает: Число — количество атрибутов, отброшенных из-за лимита

---

КоличествоОтброшенныхСобытий

Возвращает: Число — количество событий, отброшенных из-за лимита

---

КоличествоОтброшенныхЛинков

Возвращает: Число — количество линков, отброшенных из-за лимита

Методы записи

УстановитьАтрибут

Устанавливает атрибут спана; атрибут с тем же ключом перезаписывается. Значение ограничивается лимитами длины и глубины, новый ключ сверх лимита количества атрибутов отбрасывается (ОтелЛимитыСпана). Отброшенные атрибуты считает КоличествоОтброшенныхАтрибутов, о них один раз на спан пишется предупреждение в лог.

Параметр	Тип	По умолчанию	Описание
Ключ	Строка	—	Имя атрибута
Значение	Произвольный	—	Значение атрибута, допустимые типы — см. ОтелАтрибуты

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

---

ДобавитьСобытие

Добавляет событие спана (ОтелСобытиеСпана). Событие сверх лимита количества событий отбрасывается, у атрибутов события действуют лимиты количества, длины и глубины значений (ОтелЛимитыСпана).

Параметр	Тип	По умолчанию	Описание
НовоеИмя	Строка	—	Имя события
НовыеАтрибуты	ОтелАтрибуты	Неопределено	Атрибуты события
МеткаВремени	Строка	Неопределено	Время события в наносекундах от начала эпохи Unix, если событие уже произошло; по умолчанию текущее время

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

---

ЗаписатьИсключение

Записывает исключение событием exception с атрибутами:

• exception.message — описание ошибки;
• exception.type — машинный код ошибки библиотеки errors (ДиагностикаОшибок.КодОшибки, в том числе через обертки ФабрикаОшибок.Обернуть и ФабрикаОшибок.ОбернутьКонтекстом). У нативной ошибки OneScript без кода тип определяет классификатор native-errors: numeric.division_by_zero, json.reader.not_open, network.connection.refused и т.п.; если нативная ошибка обернута ошибкой без кода, берется код причины. У нераспознанной ошибки без кода атрибут не заполняется: по семантическим соглашениям он обязателен, только если нет exception.message. Тип, переданный в ДополнительныеАтрибуты, главнее кода, и тогда ошибка не классифицируется — классификация стоит порядка 1–2 мс;
• exception.stacktrace — описание ошибки и стек вызовов OneScript, включая цепочку причин (Caused by:), в том же формате, что у записи лога (ОтелУтилиты.СтекВызововИсключения).

Статус спана метод не меняет: ошибку отмечает УстановитьСтатус.

Параметр	Тип	По умолчанию	Описание
ИнформацияОбОшибке	ИнформацияОбОшибке	—	Информация об исключении, обычно ИнформацияОбОшибке() в блоке Исключение
ДополнительныеАтрибуты	ОтелАтрибуты	Неопределено	Дополнительные атрибуты события; одноимённые заменяют атрибуты exception.*

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

---

УстановитьСтатус

Устанавливает статус спана. По спецификации OpenTelemetry: статус Ок и Ошибка не могут быть понижены до НеУстановлен. Переход Ок → Ошибка игнорируется.

Параметр	Тип	По умолчанию	Описание
Значение	Число	—	Код статуса из ОтелКодСтатуса
Сообщение	Строка	""	Сообщение статуса (только для Ошибка)

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

---

ДобавитьЛинк

Добавляет линк к другому спану. Линк к контексту, известному при создании спана, лучше задать при создании через ДобавитьЛинк построителя спана: решение сэмплера (head sampling) учитывает только данные, известные при создании спана, и линк, добавленный позже, на него не влияет.

Параметр	Тип	По умолчанию	Описание
НовыйКонтекстСпана	ОтелКонтекстСпана	—	Контекст связанного спана
НовыеАтрибуты	ОтелАтрибуты	Неопределено	Атрибуты линка

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

---

ИзменитьИмя

Изменяет имя спана (UpdateName). Сэмплер принимал решение по имени, заданному при создании спана, и после переименования его не пересматривает.

Параметр	Тип	По умолчанию	Описание
НовоеИмя	Строка	—	Новое имя спана

Возвращает: ОтелСпан — ЭтотОбъект для fluent API

---

ПереопределитьВремяНачала

Изменяет время начала спана. Время начала лучше задать при создании спана (ВремяНачалатрассировщика или УстановитьВремяНачала построителя спана): тогда процессоры видят его уже в ПриНачале.

Параметр	Тип	По умолчанию	Описание
НовоеВремяНачала	Строка	—	Время начала в наносекундах от начала эпохи Unix

---

СделатьТекущим

Помещает спан в текущий контекст (аналог Java Span.makeCurrent()).

Возвращает: ОтелТокенКонтекста — токен для последующего Закрыть()

---

Завершить

Завершает спан и отправляет его в цепочку процессоров. После вызова методы записи игнорируются, повторный вызов ничего не делает.

Параметр	Тип	По умолчанию	Описание
НовоеВремяОкончания	Строка	Неопределено	Время окончания в наносекундах от начала эпохи Unix; по умолчанию текущее время

Пример

Спан = Трассировщик.НачатьСпан("SQL-запрос");
Токен = Спан.СделатьТекущим();
Попытка
    Спан.УстановитьАтрибут("db.system.name", "postgresql");
    // ... выполнение запроса ...
    Спан.ДобавитьСобытие("Запрос выполнен");
    Спан.УстановитьСтатус(ОтелКодСтатуса.Ок());
Исключение
    Спан.ЗаписатьИсключение(ИнформацияОбОшибке());
    Спан.УстановитьСтатус(ОтелКодСтатуса.Ошибка(), ОписаниеОшибки());
КонецПопытки;
Токен.Закрыть();
Спан.Завершить();

Время окончания операции, которая уже прошла:

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

См. также

• ОтелТрассировщик
• ОтелПостроительСпана
• ОтелКонтекстСпана
• ОтелКодСтатуса
• ОтелСобытиеСпана
• ОтелТокенКонтекста
• ОтелУтилиты