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

Трейсинг операций в 1С: от журнала регистрации до временной шкалы

Проведение документа, обмен с внешним сервисом или обработка фонового задания обычно состоят из нескольких шагов. Общая длительность показывает, что операция выполнялась долго, но не объясняет, на что ушло время.

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

Какую задачу решает

При разборе медленной или завершившейся с ошибкой операции важно понять:

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

Для этого используется трейс — набор связанных операций. Отдельный измеряемый шаг называется спаном. Поле trace_id объединяет спаны в один трейс, span_id идентифицирует шаг, а parent_span_id связывает его с родителем.

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

Что входит в решение

• API трейсинга: начало и завершение спанов, статусы, дополнительные атрибуты.
• Вложенные операции: связь с текущим родительским спаном через стек.
• Передача контекста: продолжение трейса в другом сеансе по TraceID и ParentSpanID.
• Граничное завершение: закрытие открытой цепочки до указанного спана включительно.
• Выборочное включение: настройка трейсинга по подсистемам.
• Просмотрщик: список трейсов, дерево спанов, временная шкала, поиск и атрибуты.
• Демо-обработка: примеры использования, большой трейс и синтетические сценарии для знакомства с интерфейсом.

Пример использования

Откроем корневой спан и вложенную операцию. При ошибке закроем цепочку до корня и передадим исключение вызывающему коду.

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

Попытка
    Если Корень <> Неопределено Тогда
        трТрейсинг.ДобавитьАтрибут("Документ", "Заказ клиента № 00482");
        Проверка = трТрейсинг.НачатьСпан("Заказы", "Проверить остатки");
    Иначе
        Проверка = Неопределено;
    КонецЕсли;

    // Проверка остатков выполняется независимо от включения трейсинга.

    Если Проверка <> Неопределено Тогда
        трТрейсинг.ЗавершитьСпан();
    КонецЕсли;

    // Остальная логика проведения документа.

    Если Корень <> Неопределено Тогда
        трТрейсинг.ЗавершитьСпан();
    КонецЕсли;
Исключение
    Если Корень <> Неопределено Тогда
        трТрейсинг.ЗавершитьСпан(
            трТрейсинг.СтатусERROR(), ОписаниеОшибки(), Корень);
    КонецЕсли;
    ВызватьИсключение;
КонецПопытки;

Если трейсинг подсистемы выключен, НачатьСпан возвращает Неопределено. Проверка результата помогает не завершить чужой родительский спан и не добавить атрибуты к другой операции.

Без явно переданных идентификаторов новый спан наследует контекст текущего родителя. Если стек пуст, создаётся новый трейс.

Завершение при ошибках не происходит само по себе: вызов API должен быть предусмотрен в обработчике исключения. Аварийное завершение процесса может оставить запись о начале без записи о завершении.

Продолжение трейса в другом сеансе

Перед запуском фонового задания или HTTP-вызовом получите текущие идентификаторы и передайте их вместе с параметрами операции:

TraceID = трТрейсинг.ТекущийTraceID();
ParentSpanID = трТрейсинг.ТекущийSpanID();

// Передать TraceID и ParentSpanID в другой сеанс.

// В принимающем сеансе:
Спан = трТрейсинг.НачатьСпан(
    "Заказы", "Обработка фонового задания", TraceID, ParentSpanID);

Попытка
    // Логика фонового задания.
    Если Спан <> Неопределено Тогда
        трТрейсинг.ЗавершитьСпан();
    КонецЕсли;
Исключение
    Если Спан <> Неопределено Тогда
        трТрейсинг.ЗавершитьСпан(
            трТрейсинг.СтатусERROR(), ОписаниеОшибки(), Спан);
    КонецЕсли;
    ВызватьИсключение;
КонецПопытки;

Передачу идентификаторов организует прикладной код. Для объединения по трейсу достаточно TraceID; ParentSpanID задаёт связь с конкретной родительской операцией. Для сопоставления времени между узлами их часы должны быть согласованы.

Граничное завершение

Третий параметр ЗавершитьСпан задаёт границу: модуль снимает спаны с вершины стека до неё включительно. Верхний спан получает переданный статус, остальные принудительно завершаются со статусом ERROR. Если граница не найдена, закрывается весь стек и записывается предупреждение.

После такого вызова отдельно закрывать спан-границу не нужно. Метод ЗавершитьСпанСОшибкой — сокращённый вариант завершения только верхнего спана с ERROR.

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

Основные события — Трейсинг.Начало и Трейсинг.Завершение. Данные спана сохраняются в JSON-комментарии. Просмотрщик использует события завершения:

{
  "trace_id": "6db6092d-0f9a-423e-990c-7377e2e577f9",
  "span_id": "883813ed-f512-4377-98ba-f05b63c22d81",
  "parent_span_id": "",
  "subsystem": "Заказы",
  "operation": "Провести документ",
  "started_at": 1731000000000,
  "time_format": "unix_ms",
  "status": "OK",
  "duration_ms": 12.34,
  "Attributes": {
    "Документ": "Заказ клиента № 00482",
    "Строк": 24
  }
}

started_at — время Unix в миллисекундах, duration_ms — длительность спана. Корневой спан не имеет родителя; просмотрщик принимает пустое значение или null. Поле time_format явно указывает формат времени.

При передаче текста ошибки в завершение добавляется поле error. Для спана с внешним TraceID также записывается событие Трейсинг.ВнешнийТрейс.

Атрибуты помогают добавить бизнес-контекст: документ, число строк, имя сервиса, результат проверки. Используйте значения, совместимые с JSON; ссылки и другие специфичные типы 1С предварительно преобразуйте в подходящее представление.

Просмотр трейсов в форме 1С

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

Выбор данных

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

Список доступных подсистем задаётся через переопределяемый модуль. Некорректные записи журнала пропускаются, их количество учитывается при загрузке. Если период захватывает только часть операции, трейс может оказаться неполным.

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

Дерево и временная шкала

• Дерево спанов показывает вложенность операций и длительности.
• Временная шкала показывает начало, продолжительность и пересечения операций.
• Цвет определяется названием операции и сохраняется при смене трейса, фильтров и страниц. Палитра ограничена, поэтому разные операции могут иметь одинаковый цвет.
• Спаны со статусом ERROR выделяются на шкале красным.
• Выбор в дереве открывает нужную страницу шкалы и переводит её к выбранному спану без автоматического изменения масштаба.
• Поиск спанов работает по операции, ID, подсистеме и атрибутам; дополнительно доступны отбор по подсистеме и переключатель «Только ошибки».
• Размер страницы — 100, 200, 500 или 1000 спанов.

Колесо мыши прокручивает шкалу по вертикали, Ctrl + колесо меняет масштаб. Перетаскивание сдвигает видимый интервал времени, кнопка «Весь трейс» возвращает обзор.

Панель списка можно скрыть, а границы между панелями — перетащить. Дерево и шкала занимают свободную высоту окна; в небольшом окне остаётся прокрутка.

Вклад потомков и атрибуты

Сворачиваемый блок «Вклад потомков» показывает непосредственные дочерние операции выбранного спана, от самых долгих к коротким. Их длительность включает время вложенных шагов.

Доля рассчитывается как длительность дочерней операции, делённая на длительность выбранного спана. Параллельные операции могут дать суммарно больше 100%. Это сравнение длительностей, а не расчёт собственного времени или критического пути.

В блоке «Детали и атрибуты» доступны атрибуты, идентификаторы, статус, время начала, длительность и JSON выбранного спана.

Включение и внедрение

Объекты решения удобно объединить в подсистему трТрейсинг:

• трТрейсинг — API спанов, сериализация и запись событий в журнал.
• трТрейсингПовтИсп — получение стека и проверка разрешения трейсинга. При переносе важно сохранить настройки повторного использования возвращаемых значений.
• трТрейсингПереопределяемый — список прикладных подсистем через ДобавитьПодсистемы.
• трВключениеТрейсинга — регистр с полями Подсистема и Включен.
• трПросмотрТрейсов — обработка просмотра с формой и макетом TraceViewerHTML.
• _Демо — генератор примеров для проверки и знакомства с решением.

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

После переноса объектов включите нужные подсистемы в регистре, добавьте вызовы API в прикладной код и проверьте настройки журнала регистрации и права доступа к нему. Для успешных спанов используется уровень «Информация», для ERROR и FATAL — «Ошибка».

Демонстрационные сценарии

Обработка _Демо содержит обычные примеры работы с API, генератор одного трейса на 100 000 спанов и отдельную команду «Красивые трейсы · Checkout».

Checkout создаёт 3 синтетических трейса по 24 спана: API Gateway, корзина, расчёт цены, резервирование, антифрод, оплата, база данных и публикация события. Основной сценарий содержит неудачную попытку оплаты и успешный повтор. Длительности заданы для иллюстрации параллельных веток; это не результаты замера работы 1С.

При каждом запуске создаются новые идентификаторы и актуальное время. Для просмотра обновите конец периода, оставьте «Все подсистемы» и найдите checkout.

Совместимость и объём данных

Для больших журналов ограничивайте выборку нужным периодом и подсистемой. На шкале можно выбрать число спанов на странице. Скорость загрузки зависит от объёма данных и ресурсов рабочей среды; наличие генератора на 100 000 спанов не означает одинаковой производительности на любой базе.

Решение помогает связать технические события с бизнес-операцией и перейти от общей длительности к конкретным шагам, параметрам и ошибкам.