Перейти к основному содержимому

Элемент проекта вида «Событие Журнала Событий»

Создание события журнала событий

Для создания события журнала событий предназначен элемент проекта Событие Журнала Событий.

дополнительно

Начиная с версии 4.0, изменился механизм регистрации событий. Теперь вместо метода ЖурналСобытий.Зарегистрировать необходимо использовать элемент проекта вида Событие Журнала Событий. Чтобы не потерять историю событий, зарегистрированных в версии «Шины» ниже 4.0, создайте нужное количество элементов проекта Событие Журнала Событий с теми же именами, которые были указаны в вызове методов ЖурналСобытий.Зарегистрировать. Если для событий были заданы свойства, то их также необходимо добавить в свойства соответствующих элементов проекта, используя те же имена. Важно выполнить все изменения до первого обновления приложения, иначе данные о событиях могут быть утеряны.

Всего есть три вида события, которые можно добавить в проект:

  • Ошибка

    События, описывающие ошибку

  • Информация

    События, несущие информационный характер

  • Операция

    События, описывающие начало и конец операции

Чтобы добавить событие, создайте новый элемент проекта Событие Журнала Событий. Задайте ему все необходимые свойства. На основе описания события будут сгенерированы типы, доступные во встроенном языке, позволяющие читать и писать значения свойств события:

  • Для событий вида Ошибка и Информация будет сгенерирован тип <ИмяСобытия>.
  • Для событий вида Операция будут сгенерированы два типа: <ИмяОперации> и <ИмяОперации>.КонтекстОперации.

Для создания события во встроенном языке следует использовать конструктор, аргументы которого — обязательные свойства события. Например, если вы добавили в проект событие ОперацияИмпортДанных с обязательным свойством Задание, то создать его можно следующим образом:

пер СобытиеИмпортДанных = новый ОперацияИмпортДанных(Задание = "КлючЗадания")

Необязательные свойства можно задать через свойства объекта (МоеСобытие.НеобязательноеСвойствоСобытия = "Значение"), а также через свойства контекста операции (Контекст.НеобязательноеСвойствоСобытия = "Значение"). Уже заданные обязательные значения можно изменить таким же образом.

Для регистрации события во встроенном языке используются специальные методы события:

  • метод Записать() для событий вида Информация и Ошибка;
  • метод ЗаписатьНачало() для события вида Операция.

Например, записать начало операции можно следующим образом:

исп Контекст = СобытиеИмпортДанных.ЗаписатьНачало()

Операции, иерархия событий

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

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

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

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

Пример иерархии событий, зарегистрированных через вложенные операции:

исп Контекст1 = новый Операция1().ЗаписатьНачало()
область
исп Контекст2 = новый Операция2().ЗаписатьНачало()
новый Событие1().Записать()
;
новый Событие2().Записать()

В результате будут зарегистрированы события, из которых можно построить иерархию, используя свойство СобытиеЖурналаСобытий.Родитель):

  • НачалоОперации1
    • НачалоОперации2
      • Событие1
    • КонецОперации2
    • Событие2
  • КонецОперации1

Еще одна особенность операций — возможность автоматической регистрации ошибок и маркировки операций как неудачных.

исп Контекст = новый Операция().ЗаписатьНачало()
...
выбросить новый ИсключениеВыполенния("Пояснения")

В результате выполнения такого кода в журнал попадут:

  • Операция
    • ИсключениеВыполнения с описанием «Пояснения»
  • Операция с признаком СобытиеЖурналаСобытий.Успешно = Ложь

Исключения не отлавливаются автоматически — их нужно обрабатывать.

попытка
исп Контекст = новый Операция().ЗаписатьНачало()
...
выбросить новый ИсключениеВыполенния("Пояснения")
поймать Искл: Исключение
// Поймали исключение, но в журнал оно все равно попадет, т. к. операция Операция была прервана по исключению
;

Пример поиска событий, произошедших в контексте операции:

пер ИдОперации1: Ууид
пер ИдОперации2: Ууид

область
исп Контекст1 = новый Операция1().ЗаписатьНачало()
ИдОперации1 = Контекст1.Ид

область
исп Контекст2 = новый Операция2().ЗаписатьНачало()
новый Событие1().Записать()
новый Событие2().Записать()
ИдОперации2 = Контекст2.Ид
;
;

пер СобытийВОперации1 = 0

пер РезультатПоиска = ЖурналСобытий.Найти(ИдОперации = ИдОперации1)
пока РезультатПоиска.Следующий()
СобытийВОперации1 ++
;
// Ожидается:
// СобытийВОперации1 = 6
// События:
// Открытие Контекст1
// Открытие Контекст2
// Событие1
// Событие2
// Закрытие Контекст2
// Закрытие Контекст1

Получение свойств события

Получить свойства события можно тремя способами:

  • У событий конкретных типов можно обратиться к свойству через точку, например:

    МоеСобытие.СвойствоСобытия
  • У всех событий есть метод ПолучитьСвойство(Имя: Строка), который возвращает значение свойства Имя события или Неопределено, если нет свойства с указанным именем:

    МоеСобытие.ПолучитьСвойство("СвойствоСобытия")
  • У каждого события есть свойство Свойства, которое содержит ЧитаемоеСоотвествие наименований свойств события и их значений. Таким образом, вы можете получить значение свойства, передав его имя в качестве ключа:

    МоеСобытие.Свойства["СвойствоСобытия"]

Если свойство было удалено, вы можете получить к нему доступ с использованием метода ПолучитьСвойство("УдаленноеСвойство"). Если свойство было переименовано, вы все еще можете получить его значение у старых событий, записанных до переименования:

  • с использованием метода ПолучитьСвойство, обратившись к свойству по старому либо по новому имени;
  • обратившись к свойству через точку по новому имени.

Журнал событий в панели управления

Чтобы открыть журнал событий, в панели управления, на вкладке Приложения, выберите нужное приложение. В карточке приложения кликните на иконку и выберите Посмотреть журнал событий в открывшемся меню:

Чтобы найти необходимые события, используйте строку поиска.

Вы также можете использовать Фильтры, чтобы отфильтровать события:

  • по дате,
  • по важности,
  • по виду,
  • по имени.

Чтобы отобрать события по значению их свойств, используйте Продвинутый фильтр:

События из старых версий приложения также будут найдены во время поиска, даже если они были переименованы или удалены из проекта.

Вы можете скопировать информацию о событии в виде:

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

Рекомендации по работе с событиями журнала событий

  • Рекомендуется не удалять описания событий из проекта.
  • Рекомендуется не удалять описания свойств событий из проекта.
  • Настоятельно не рекомендуется менять тип в описании свойства события. При этом вы можете расширять тип (например, указать строку большей длины, число большей длины и т. д.).
  • Настоятельно не рекомендуется переиспользовать идентификаторы и имена типов и свойств событий. Рекомендуется избегать ситуаций, когда было создано событие с определенными свойствами в версии 1, после чего данное событие или свойство было удалено в версии 2, а в версии 3 добавлено новое событие или свойство с тем же идентификатором или именем, что и в версии 1.
  • Для улучшения читаемости рекомендуется именовать события с префиксами «ошибка», «операция», «событие». Рекомендуется использовать существительное с определяющими словами, например: СобытиеУспешныйИмпорт, ОперацияОтладкаИмпорта, ОшибкаПреобразованияДанных.
  • Для важности события рекомендуется использовать значения по умолчанию, заданные в описании элемента проекта. Это повысит не только читаемость кода, но и упростит интерпретацию событий администратором (так как событие определенного вида всегда будет иметь одну и ту же важность).
  • Рекомендуется избегать длинных строковых значений, содержащих детальное описание события. Рекомендуется использовать свойства события и ФорматПредставления для формирования хорошо читаемого представления события.