Единый API трейсинга операций в 1С: трассировка спанов, распределённые трейсы и журнал регистрации как система наблюдения

Проблема

Каждая операция в 1С — это цепочка вложенных шагов: чтение данных, обработка, запись в справочник, вызов фонового задания, обращение к внешнему сервису. Когда что-то идёт не так, стандартных инструментов не хватает:

• непонятно, где именно операция замедлилась или упала;
• нет единой «нити» связи между шагами одной бизнес-операции;
• нельзя проследить путь запроса из внешней системы через фоновые задания и HTTP-ручки;
• журнал регистрации превращается в хаос из разрозненных записей.

Решение — ввести трейсинг: каждую операцию разбиваем на спаны, связываем их в дерево через TraceID и ParentSpanID и фиксируем в журнале регистрации в структурированном виде.

Что предлагает модуль

трТрейсинг — это:

1. Единый API для создания и завершения спанов с записью в журнал регистрации.
2. Стек спанов — автоматическое связывание вложенных операций в цепочку «родитель → ребёнок».
3. Поддержка распределённых трейсов — связывание спанов между сеансами (фоновые задания, HTTP, интеграции) через внешний TraceID.
4. Гарантированное завершение спанов при любом исходе.
5. Граничный режим — «откат» стека до указанного спана.
6. Обработка просмотра трейсов с построением дерева спанов в HTML.

Основные сценарии

1. Обычный режим (вложенные операции)

Пример: обработчик, внутри которого выполняется несколько подопераций.

Спан = трТрейсинг.НачатьСпан("Заказы", "Провести документ");
    трТрейсинг.НачатьСпан("Заказы", "Проверка остатков");
        // ... логика
    трТрейсинг.ЗавершитьСпан(трТрейсинг.СтатусOK());
    трТрейсинг.НачатьСпан("Заказы", "Запись движений");
        // ... логика
    трТрейсинг.ЗавершитьСпан(трТрейсинг.СтатусOK());
трТрейсинг.ЗавершитьСпан(трТрейсинг.СтатусOK());

Как это работает:

• если TraceID и ParentSpanID не переданы, родитель берётся из вершины стека;
• TraceID наследуется от родителя, а если стек пуст — генерируется новый.

2. Распределённый трейс (внешний TraceID)

Нужен, когда операция начинается в одном сеансе, а продолжается в другом — например, в фоновом задании или при вызове из внешней системы.

// Получаем текущий контекст
TraceID  = трТрейсинг.ТекущийTraceID();
SpanID   = трТрейсинг.ТекущийSpanID();
// Передаём их в параметры фонового задания / HTTP
// ...
// В фоновом задании связываемся с исходным спаном
Спан = трТрейсинг.НачатьСпан("Заказы",
        "Обработка фонового задания", TraceID, SpanID);
    // ...
трТрейсинг.ЗавершитьСпан(трТрейсинг.СтатусOK());

Так строится полная цепочка: корневой спан внешнего запроса → спан-обработчик → спан фонового задания.

3. Завершение при ошибках

При возникновении исключения или ошибки спан завершается со статусом ERROR через ЗавершитьСпанСОшибкой, либо принудительно через граничный режим — все открытые спаны закрываются разом, и стек не остаётся с «зависшими» незакрытыми спанами.

4. Граничный режим (откат стека)

Полезно, когда внутри одной функции открыто несколько спанов, а при ошибке нужно закрыть их все разом до границы.

Граница = трТрейсинг.НачатьСпан("Доставка", "Расчёт стоимости");
    трТрейсинг.НачатьСпан("Доставка", "Шаг 1");
    трТрейсинг.НачатьСпан("Доставка", "Шаг 2");
    // Если здесь ошибка...
    трТрейсинг.ЗавершитьСпан(
        трТрейсинг.СтатусERROR(),
        "Не удалось рассчитать стоимость",
        Граница);   // закрываем всё до границы включительно

Поведение:

• те спаны, что глубже границы, завершаются принудительно со статусом ERROR;
• если граница не найдена в стеке — принудительно завершается весь стек, а в журнал пишется предупреждение.

Что попадает в журнал регистрации

Каждый спан пишется в журнал в виде JSON. Начало спана:

{
  "trace_id": "...",
  "span_id": "...",
  "parent_span_id": "...",
  "subsystem": "Заказы",
  "operation": "Провести документ",
  "started_at": 1731000000000,
  "status": "STARTED"
}

Завершение спана (добавляются статус, длительность, атрибуты и ошибка):

{
  "trace_id": "...",
  "span_id": "...",
  "parent_span_id": "...",
  "subsystem": "Заказы",
  "operation": "Провести документ",
  "started_at": 1731000000000,
  "status": "OK",
  "duration_ms": 12.34,
  "Attributes": { "ключ": "значение" }
}

Для внешних (распределённых) трейсов дополнительно пишется отметка Трейсинг.ВнешнийТрейс с признаком "source": "external".

Регистр сведений для включения подсистем

Трейсинг включается выборочно, по подсистеме. Для этого используется регистр сведений трВключениеТрейсинга с реквизитами Подсистема и Включен. Реестр подсистем наполняется через переопределяемый модуль:

Процедура ДобавитьПодсистемы(МассивПодсистем) Экспорт
    МассивПодсистем.Добавить(Обработки._Демо.ИмяПодсистемы());
КонецПроцедуры

Это даёт гибкость: например, включить трейсинг только для «Заказов» и «Доставки», оставив остальные подсистемы на прежнем поведении.

Обработка просмотра трейсов

Обработка трПросмотрТрейсов — это рабочее место аналитика/разработчика для разбора операций. Она состоит из двух страниц, между которыми удобно переключаться: на первой получаем и отбираем спаны, на второй — визуально разбираем выбранный трейс.

Страница 1 — «Получение спанов»

Здесь задаются фильтры и выгружаются спаны из журнала регистрации:

• Подсистема — выбор из списка подсистем, для которых разрешён трейсинг (список наполняется автоматически через ДобавитьПодсистемы);
• Стандартный период — диапазон дат, за который собираются данные (ДатаНачала / ДатаОкончания);
• Кнопка «Получить спаны» — выполняет запрос к журналу регистрации по событию Трейсинг.Завершение;
• Таблица спанов — наглядный список полученных записей: DurationMS, TraceID, SpanID, ParentSpanID, Operation, Status, Attributes, Error.

Полученные записи парсятся из JSON-комментария журнала и раскладываются по колонкам. Некорректные записи не «роняют» обработку — они пропускаются с сообщением в окно.

Страница 2 — «Просмотр спанов»

На этой странице выбранный трейс собирается в связное дерево и показывается в HTML-представлении:

• Список трейсов — уникальные TraceID из выгруженных спанов (для быстрого выбора нужной операции);
• Дерево спанов — вложенность отображается отступами и префиксом ^92;^72;, корневые спаны — без отступа;
• Длительность — по каждому спану в отдельной колонке;
• Статус — цветовая маркировка (OK — зелёный, ошибки — красный);
• Атрибуты — значения, добавленные через ДобавитьАтрибут, в компактном виде ключ: значение;
• Ошибка — текст ошибки для спанов со статусом ERROR / FATAL.

HTML-представление формируется на сервере по дереву спанов (массив корневых + соответствие «родитель → дети») и открывается интерактивно при выборе трейса. Атрибуты, включая вложенные структуры и массивы, компактно сериализуются, длинные значения обрезаются.

Как внедрить

Внедрение сводится к созданию единой подсистемы трТрейсинг, которая объединяет все объекты модуля. Так вся функциональность трейсинга собирается в одном месте, подключается одной подсистемой и легко переносится между конфигурациями.

Создайте подсистему трТрейсинг и включите в неё следующие объекты:

Общие модули

• трТрейсинг — основной API трейсинга. Содержит весь набор экспортных методов для работы со спанами: НачатьСпан, ЗавершитьСпан, ЗавершитьСпанСОшибкой, ДобавитьАтрибут, ТекущийTraceID, ТекущийSpanID, а также функции статусов (СтатусOK, СтатусERROR, СтатусFATAL, СтатусSTARTED). Отсюда вызывается весь остальной код приложения.
• трТрейсингПовтИсп — повторное использование. Здесь живёт стек спанов текущего сеанса (ссылка на массив, который модифицируется добавлением/удалением спанов), вспомогательные механизмы и запись трейсинга в журнал регистрации.
• трТрейсингПереопределяемый — переопределяемый модуль. Точка расширения: через метод ДобавитьПодсистемы наполняет реестр подсистем, для которых разрешён трейсинг. Адаптируется под конкретную конфигурацию без изменения основного модуля.

Обработка

• трПросмотрТрейсов — обработка просмотра трейсов. Рабочее место аналитика/разработчика для разбора операций. Состоит из двух страниц: «Получение спанов» (фильтры и выгрузка записей из журнала регистрации) и «Просмотр спанов» (выбранный трейс собирается в дерево и выводится в HTML-представлении).

Регистр сведений

• трВключениеТрейсинга — регистр сведений с реквизитами Подсистема и Включен. Позволяет выборочно включать и выключать трейсинг по каждой подсистеме независимо.

Заключение

Модуль трТрейсинг даёт компактный и предсказуемый способ наблюдать за операциями в 1С. Главные плюсы:

• видимость — каждая операция видна в журнале как структурированный JSON;
• связанность — дерево спанов восстанавливает полную картину операции;
• распределённость — трейс не рвётся при передаче между сеансами;
• контроль — гарантированное завершение спанов и защита от «висящих» незакрытых спанов;
• надёжность — корректная работа при откате транзакции: стек и метрики спанов не теряются, трейс сохраняет полную картину даже при отмене изменений;
• атрибуты — возможность добавлять к любому спану произвольные пары «ключ: значение» через ДобавитьАтрибут — они сохраняются в журнале и отображаются в обработке просмотра.