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

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

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

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

Начиная с версии 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 + 1
;
// Ожидается:
// СобытийВОперации1 = 6
// События:
//    Открытие Контекст1
//       Открытие Контекст2
//          Событие1
//          Событие2
//       Закрытие Контекст2
//    Закрытие Контекст1

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

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

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

  МоеСобытие.СвойствоСобытия

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

  МоеСобытие.ПолучитьСвойство("СвойствоСобытия")

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также

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