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

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

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

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