ОтелКонтекст
Модуль для управления текущим контекстом выполнения.
Описание
Реализует generic key-value хранилище контекста (аналог Java SDK: io.opentelemetry.context.Context). Каждый поток исполнения имеет свой стек контекстов. Контекст — это ФиксированноеСоответствие ключ → значение. Ключи — ОтелКлючКонтекста, сравниваются по ссылке.
Стек хранится в данных потока исполнения (ТекущийПоток().Данные). Движок выделяет отдельный поток исполнения основному скрипту, каждому фоновому заданию и каждому запросу веб-сервера. Другие потоки стек не видят, поэтому синхронизация не нужна, а после завершения потока движок освобождает его данные сам.
Важно: Ключи для спана и Baggage являются приватными переменными модуля. Для работы со спанами и Baggage используйте специализированные методы
ТекущийСпан(),ТекущийBaggage()и т.д.
Функции
СоздатьКлюч
Создает новый ключ контекста. Ключи сравниваются по ссылке — два ключа с одинаковым именем являются разными ключами.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Имя | Строка | — | Имя ключа (для отладки) |
Возвращает: ОтелКлючКонтекста — новый ключ контекста
Текущий
Возвращает текущий контекст (верхний элемент стека). Если стек пуст, возвращает пустой иммутабельный контекст.
Возвращает: ФиксированноеСоответствие — текущий контекст (иммутабельный)
Получить
Возвращает значение из текущего контекста по ключу.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Ключ | ОтелКлючКонтекста | — | Ключ контекста |
Возвращает: Произвольный, Неопределено — значение по ключу или Неопределено
ТекущийСпан
Возвращает текущий спан из контекста текущего потока.
Возвращает: ОтелСпан, Неопределено — текущий спан или Неопределено
ТекущийBaggage
Возвращает текущий Baggage из контекста текущего потока.
Возвращает: ОтелBaggage, Неопределено — текущий Baggage или Неопределено
ПолучитьИзКонтекста
Возвращает значение из переданного контекста по ключу.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Контекст | ФиксированноеСоответствие, Соответствие | — | Контекст |
Ключ | ОтелКлючКонтекста | — | Ключ контекста |
Возвращает: Произвольный, Неопределено — значение по ключу или Неопределено
КонтекстСоЗначением
Создает новый иммутабельный контекст с установленным значением.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Контекст | ФиксированноеСоответствие, Соответствие | — | Исходный контекст |
Ключ | ОтелКлючКонтекста | — | Ключ контекста |
Значение | Произвольный | — | Значение для установки |
Возвращает: ФиксированноеСоответствие — новый иммутабельный контекст
СпанИзКонтекста
Возвращает спан из переданного контекста или из текущего контекста потока.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
КонтекстОбъект | ФиксированноеСоответствие, Соответствие, Неопределено | Неопределено | Явный контекст |
Возвращает: ОтелСпан, Неопределено — спан или Неопределено
BaggageИзКонтекста
Возвращает Baggage из переданного контекста или из текущего контекста потока.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
КонтекстОбъект | ФиксированноеСоответствие, Соответствие, Неопределено | Неопределено | Явный контекст |
Возвращает: ОтелBaggage, Неопределено — Baggage или Неопределено
КонтекстСоСпаном
Создает новый иммутабельный контекст (копию переданного) с установленным спаном.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Контекст | ФиксированноеСоответствие, Соответствие | — | Исходный контекст |
Спан | ОтелСпан, ОтелНезаписывающийСпан | — | Спан для установки; незаписывающий спан из контекста спана создаёт ОтелСпаны.Обернуть |
Возвращает: ФиксированноеСоответствие — новый иммутабельный контекст со спаном
КонтекстСBaggage
Создает новый иммутабельный контекст (копию переданного) с установленным Baggage. Текущий контекст потока не меняется: такой контекст передают пропагатору (Внедрить) или делают текущим через ПрисоединитьКонтекст.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Контекст | ФиксированноеСоответствие, Соответствие | — | Исходный контекст |
Багаж | ОтелBaggage | — | Baggage для установки |
Возвращает: ФиксированноеСоответствие — новый иммутабельный контекст с Baggage
УстановитьЗначение
Делает текущим контекст, в котором к значениям текущего контекста добавлено значение по ключу (или заменено прежнее). Аналог Java: Context.current().with(key, value).makeCurrent(). Новый контекст помещается на вершину стека потока, как при ПрисоединитьКонтекст; предыдущий восстанавливают Закрыть() токена или ОтсоединитьКонтекст(Токен).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Ключ | ОтелКлючКонтекста | — | Ключ контекста (см. СоздатьКлюч) |
Значение | Произвольный | — | Значение для установки |
Возвращает: ОтелТокенКонтекста — токен для восстановления предыдущего контекста
СделатьСпанТекущим
Делает спан текущим: помещает на вершину стека потока копию текущего контекста с этим спаном, остальные значения контекста (например, Baggage) сохраняются. Через эту функцию работает СделатьТекущим() у ОтелСпан и ОтелНезаписывающийСпан. Завершение спана токен не закрывает: закройте его сами.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Спан | ОтелСпан, ОтелНезаписывающийСпан | — | Спан, который станет текущим |
Возвращает: ОтелТокенКонтекста — токен для восстановления предыдущего контекста
СделатьBaggageТекущим
Делает Baggage текущим: помещает на вершину стека потока копию текущего контекста с этим Baggage, остальные значения контекста (например, текущий спан) сохраняются. Через эту функцию работает ОтелBaggage.СделатьТекущим().
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Багаж | ОтелBaggage | — | Baggage, который станет текущим |
Возвращает: ОтелТокенКонтекста — токен для восстановления предыдущего контекста
ПрисоединитьКонтекст
Присоединяет новый контекст к текущему потоку (Attach Context). Помещает контекст на вершину стека.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Контекст | ФиксированноеСоответствие, Соответствие | — | Контекст для установки |
Возвращает: ОтелТокенКонтекста — токен для последующего ОтсоединитьКонтекст()
ОтсоединитьКонтекст
Отсоединяет контекст по токену, восстанавливая предыдущий (Detach Context).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Токен | ОтелТокенКонтекста | — | Токен, возвращенный из ПрисоединитьКонтекст() |
Возвращает: Булево — Истина при корректном порядке, Ложь при нарушении
Очистить
Очищает контекст текущего потока.
Пример
// RAII-паттерн
Токен = Спан.СделатьТекущим();
Попытка
// ... работа в контексте спана ...
Исключение
Спан.ЗаписатьИсключение(ИнформацияОбОшибке());
КонецПопытки;
Токен.Закрыть();
Спан.Завершить();
// Явный Attach/Detach
Токен = ОтелКонтекст.ПрисоединитьКонтекст(НовыйКонтекст);
// ... работа ...
ОтелКонтекст.ОтсоединитьКонтекст(Токен);
// Своё значение в текущем контексте
КлючЗапроса = ОтелКонтекст.СоздатьКлюч("request.id");
Токен = ОтелКонтекст.УстановитьЗначение(КлючЗапроса, "42");
ИдЗапроса = ОтелКонтекст.Получить(КлючЗапроса); // "42"
Токен.Закрыть();