Журнал событий (Event Logging)

Win32: централизованное протоколирование событий

Автор: Серебряков Алексей (Smooky)
QUIBECK INC.
Источник: RSDN Magazine #3-2007

Опубликовано: 14.11.2007
Версия текста: 1.0

Предисловие Теория Рекомендации по протоколированию событий События в журнале Элементы журнала событий Практика Файл сообщений Послесловие

«А навалил та, а навалил та сколько! Ужас…»
Слова одного программиста при просмотре файла лога

Предисловие

Многие из Вас, наверное, принимали участие в крупных и долгосрочных проектах, где разрабатывалось приличное количество модулей, использовались многочисленные библиотеки, сценарии и т.д. Мне тоже приходилось участвовать в таких проектах. Один из них и натолкнул меня на мысль о создании этой статьи. В том проекте участвовало множество программистов, разработчиков и тестеров. Каждый разработчик писал небольшой модуль протоколирования (логирования, от англ. logging, - снимать, записывать показания с прибора) и трассировки своих модулей и наработок. Кто-то писал свои утилиты, которые потом разбирали эти протоколы, кто-то использовал буферизованный вывод, т.е. какого-то чёткого регламента по этой деятельности не было. Результатом всей этой деятельности стало большое количество разбросанных текстовых и бинарных файлов с понятными и непонятными расширениями, непонятного формата и содержания. Понятно, что при такой организации так и должно было случиться. Хуже того, бывает и так, что при выходе финальной версии не удаётся всё это убрать, и всё это оказывается у пользователя и заказчика.

Для решения этой проблемы операционная система Windows предоставляет такой сервис и программный интерфейс, как Eventlog. Этот инструментарий относится к числу базовых сервисов Windows, т.е. поставляется с самой системой и система сама же его использует. Стоит заметить, что эта возможность есть только у систем семейств WinNT/XP, т.к. приложение для протоколирования событий является сервисом. Также стоит заметить, что в Windows Vista и Windows Longhorn этот сервис существенно переработан, новый вариант в этой статье рассматриваться не будет.

Мы не будем также рассматривать этот замечательный инструмент с точки зрения администраторов, сборщиков журналов и прочих персон, которые призваны управлять системой. Итак, приступим.

Теория

Рисунок 1.

Наверное, почти все разработчики используют в своих программах протоколирование событий при выявлении ошибок, отладке и диагностировании приложений. Но даже после успешного сбора и просмотра статистики иной раз бывает сложно проанализировать, что же всё-таки случилось и в каком месте? Так вот, сервис «Журнал событий» является стандартным, централизованным способом сбора статистики и просмотра сообщений о событиях, поступающих от приложений, сервисов операционной системы и аппаратных устройств. Средство для просмотра этих событий является оснасткой Microsoft Management Console. В Windows XP Rus эта оснастка запускается так: Пуск->Настройка->Панель управления->Администрирование->Просмотр Событий (Event Viewer).

Рекомендации по протоколированию событий

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

Сообщение в журнале событий – это, прежде всего, информация, способная помочь вам, администратору и даже пользователю понять, какая проблема возникла в приложении и как её устранить. В частности, это событие может предназначаться специалисту технической поддержки в вашей компании, и даже ему будет тоскливо читать сообщение: «Процесс А не смог прочитать 0x05 байт 0x2-ого сектора дисковода В». Поэтому идеальное сообщение должно помочь пользователю ответить на следующие вопросы:

• Что случилось и почему?
• Что ему (пользователю) делать дальше?
• Что он (пользователь) может сделать, чтобы этого больше не повторилось?

Могут пригодиться и следующие рекомендации:

• Избегайте условных ошибок. Если вы можете спрогнозировать ошибку, которая может случиться в случае выполнения некоторого действия, перепишите свой код так, чтобы пользователь не получал сообщения об ошибке.
• Напишите текстовое сообщение для каждой известной ошибки.
• Используйте системные коды и сообщения об ошибках.
• Предоставьте пользователю хотя бы один вариант решения проблемы, возникшей вследствие вашей ошибки.
• Не используйте технические термины, жаргон, сленг и аббревиатуры.
• В диалоговых сообщениях используйте именно необходимые кнопки (такие как Yes, No, Cancel).

Соглашения о стиле содержания сообщения:

• Используйте подробные, но простые предложения.
• Не используйте слова, состоящие из одних заглавных букв.
• Используйте точную семантику. Например, вместо сообщения “Bad size” лучше всё-таки указать пользователю правильный размер.

Это неполный список рекомендаций, взятый из MSDN. На самом деле в популярных книгах, например, у Саттера, есть более интересные рекомендации.

События в журнале

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

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

Элементы журнала событий

Журналы

Всю информацию о настройках журнала сервис берёт из реестра: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog.

Каждая ветка в этом ключе – это журнал. Изначально их всего три, но можно создавать свои журналы, и регистрировать свои приложения как источники событий для этих журналов.

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

Источники событий

Каждая подветка в ветке Eventlog – это источник событий.

Например, для приложения MySuperApp.EXE, которое будет записывать события в журнал Application, необходимо создать такую подветку:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\MySuperApp

Здесь MySuperApp – это произвольное имя, по которому сервис (журнал) будет опознавать события, поступающие от нашего приложения. Каких либо соглашений об имени в документации не указано, но видимо, имя должно быть уникально в пределах одной подветки. Обычно используется название приложения или исполняемого модуля. По сути дела, это и есть регистрация приложения в сервисах Event Logging и Event Viewer.

Пользовательские приложения и сервисы должны либо регистрировать себя в журнале Application, либо создавать свой журнал. Журнал Security используется только системой. Драйверы устройств должны использовать журнал System.

Каждый источник событий (как мы уже знаем, приложение) должен в своей подветке определить перечисленные ключи. Они помогают Event Viewer сопоставлять сообщения и подставляемые параметры из ресурсной DLL-библиотеки с идентификаторами в приложении (позже я это продемонстрирую на примере):

Фактически получается, что когда приложение вызовет функции RegisterEventSource или OpenEventLog, сервис Eventlog будет искать в реестре ветку MySuperApp, чтобы вернуть описатель журнала. Если он не найдет ветку с именем MySuperApp, по умолчанию будет использован журнал Application.

Рисунок 2.

Вот, собственно, основные теоретические сведения. Можно приступить к практическим занятиям.

Практика

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

Файл сообщений

Категории, сообщения и подставляемые параметры можно разместить как в одном файле, так и в разных. Для удобства и наглядности разместим всё в одном файле MYEVT_ENG.MC.

Категории событий

Категории событий – это всего лишь числовые идентификаторы, которые помогают фильтровать записи при просмотре журнала в Event Viewer. Каждый источник событий может обозначить свои категории любым числом. Надо только учесть, что они должны располагаться в начале файла сообщений последовательно (по порядку) и начинаться с 1. Подробное описание формата файла *.MC можно найти в в MSDN.

; /*
;   HEADER SECTION
;  */
SeverityNames=(Success=0x0:STATUS_SEVERITY_SUCCESS
               Informational=0x1:STATUS_SEVERITY_INFORMATIONAL
               Warning=0x2:STATUS_SEVERITY_WARNING
               Error=0x3:STATUS_SEVERITY_ERROR
              )
;
;
FacilityNames=(System=0x0:FACILITY_SYSTEM
               Runtime=0x2:FACILITY_RUNTUME
               Stubs=0x3:FACILITY_STUBS
               Io=0x4:FACILITY_IO_ERROR_CODE
              )
;
; /*
;    MESSAGE DEFINITION SECTION
;  */
;
; /* Categories */
;

MessageIdTypedef=WORD

MessageId=0x1
SymbolicName=CAT_1
Language=English
Category 1
.
MessageId=0x2
SymbolicName=CAT_2
Language=English
Category 2
.
MessageId=0x3
SymbolicName=CAT_3
Language=English
Category 3
.

Обратите внимание на обязательный разделитель категорий - точку.

Идентификаторы событий

Каждый идентификатор события уникален в пределах файла сообщений. Каждый источник событий может определять свои собственные идентификаторы и связанные с ними строки. В Event Viewer при просмотре журнала мы как раз и видим эти строки (см. рисунок).

Формат кода идентификатора события выглядит так (впрочем, это соглашение, принятое в Windows):

Важность ошибки (Severity):

• 00 – Success
• 01 – Informational
• 10 – Warning
• 11 – Error

Принадлежность (Customer bit):

• 0 – Системный
• 1 – Пользовательский
• Зарезервирован (R)
• Код подсистемы (Facility)
• Код ошибки (Code)

Подробные пояснения можно найти в книге Рихтера или в MSDN.

Строки сообщений

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

; /* Messages */

MessageIdTypedef=DWORD

MessageId=0x100
Severity=Error
Facility=Runtime
SymbolicName=MSG_ERR_1
Language=English
My error message 1
.
MessageId=0x200
Severity=Error
Facility=Informational
SymbolicName=MSG_ERR_2
Language=English
My another error message %1

; /* Insert string parameters */

MessageId=1000
Severity=Success
Facility=System
SymbolicName=PARAM_1
Language=English
Parameter1
.

Итак, мы написали файл MYEVT_ENG.MC. Теперь нам понадобится утилита MessageCompiler (MC.EXE), которая поставляется с MSVC6.0 и Platform SDK. Это консольное приложение скомпилирует файл сообщений:

mc.exe –u –U myevt_eng.mc

В результате мы получим следующие файлы: MYEVT_ENG.H (определения символических имён), Msg00001.bin (бинарный ресурс для каждого языка), MYEVT_ENG.RC (в нём подключены бинарные ресурсы). Кстати, файл WINERROR.H, поставляемый с Microsoft Visual Studio, именно так и сгенерирован.

Теперь скомпилируем файл ресурсов MYEVT_ENG.RC:

rc.exe –r myevt_eng.rc

В результате мы получим файл MYEVT_ENG.RES. И, наконец-то, скомпилируем библиотеку:

link.exe –dll –noentry –out:my_msgs.dll myevt_eng.res

Теперь нам осталось зарегистрировать источник событий и написать код, использующий журнал событий. К сожалению, Microsoft не предоставляет никаких утилит для регистрации источника событий (мне, по крайней мере, они неизвестны), поэтому делать все придется ручками. На целевой машине это можно сделать всего один раз, например, при инсталляции.

Регистрация источника событий

Для регистрации источника событий достаточно всего лишь определить несколько ключей в реестре (описание ключей приведены выше).

          // Наш источник событий будет посылать сообщения в журнал Application

TCHAR szAppLog[MAX_PATH] = 
  _T(“\\SYSTEM\CurrentControlSet\\Services\\Eventlog\\Application\\MySuperApp”);
  TCHAR szMsgFile[] = _T(“my_msgs.dll”);
DWORD dwCategoryCount = 3; // мы определили 3 категории в файле MYEVT_ENG.MC
DWORD dwTypesSupported = 
  EVENTLOG_ERROR_TYPE | EVENTLOG_INFORMATION_TYPE | EVENTLOG_WARNING_TYPE;

::RegCreateKeyEx(
  HKEY_LOCAL_MACHINE, szAppLog, 0, NULL, REG_OPTION_NON_VOLATILE, 
  KEY_WRITE | KEY_SET_VALUE, NULL, &hKey, &dwDisposition);

::RegSetValue(
  hKey, _T(“CategoryMessageFile”), REG_EXPAND_SZ, (LPBYTE)szMsgFile,
  (DWORD)(_tcslen(szMsgFile) + 1) * sizeof(TCHAR));
::RegSetValue(
  hKey, _T(“EventMessageFile”), REG_EXPAND_SZ, (LPBYTE)szMsgFile,
  (DWORD)(_tcslen(szMsgFile) + 1) * sizeof(TCHAR));
::RegSetValue(
  hKey, _T(“ParameterMessageFile”), REG_EXPAND_SZ, (LPBYTE)szMsgFile, 
  (DWORD)(_tcslen(szMsgFile) + 1) * sizeof(TCHAR));
::RegSetValue(
  hKey, _T(“CategoryCount”), REG_DWORD,
    (LPBYTE)&dwCategoryCount, sizeof(DWORD));
::RegSetValue(
  hKey, _T(“TypesSupported”), REG_DWORD, (LPBYTE)&dwTypesSupported, 
  sizeof(DWORD));

Теперь сервис Eventlog готов принимать сообщения о событиях, а Event Viewer – показывать их. Осталось только это использовать.

Использование журнала событий

          #include <windows.h>
#include <iostream>
#include <tchar.h>
#include “myevt_eng.h” // подключаем сгенерированный файл идентификаторов#pragma comment(linker, "/subsystem:console")
#pragma comment(lib, "advapi32.lib")

usingnamespace std;

int _tmain(int argc, TCHAR* argv[])
{
  // Подключаемся к журналу событий
  
HANDLE hEventSource = ::RegisterEventSource(NULL, _T("MySuperApp"));

  if (hEventSource == NULL)
{
  cout << _T("Could not register the event source.") << endl;
  return 0 ;
}

// Теперь можем посылать события в журналif (
!::ReportError(
    hEventSource, EVENTLOG_ERROR_TYPE, 
    CAT_1, MSG_ERR_1, NULL, 0, 0, NULL, NULL))
{
  cout << _T("Could not report the event.") << endl;
}

// Отключаемся от журнала событий

::DeregisterEventSource(hEventSource);

return 0 ;
}

Здесь стоит пояснить две важные функции: RegisterEventSource и ReportEvent.

HANDLE RegisterEventSource(LPCTSTR lpUNCServerName, LPCTSTR lpSourceName)

lpUNCServerName – UNC-имя удалённого компьютера (NULL - локальный).

lpSourceName – это имя источника события, который будет отсылать сообщения в журнал. В нашем примере это был MySuperApp. Нельзя использовать журнал Security (функция вернёт INVALID_HANDLE_VALUE). Если имя источника события не было найдено в реестре (в подключе \Eventlog), будет использоваться журнал Application.

Функция возвращает описатель журнала или NULL.

BOOL ReportEvent(HANDLE hEventLog, WORD wType, WORD wCategory, DWORD dwEventID, PSID lpUserSid, WORD wNumStrings, DWORD dwDataSize, LPCTSTR* lpStrings, LPVOID lpRawData)

hEventLog – описатель, который вернула функция RegisterEventSource.

wType – тип события (EVENTLOG_SUCCESS, EVENTLOG_AUDIT_FAILURE, EVENTLOG_AUDIT_SUCCESS, EVENTLOG_ERROR_TYPE, EVENTLOG_WARNING_TYPE, EVENTLOG_INFORMATION). Указать можно только один тип.

wCategory – категория (см. Категории событий)

dwEventType – сообщение (см. Идентификаторы событий)

lpUserSid – указатель на структуру SID.

wNumStrings – количество подставляемых параметров в lpStrings. Каждая строка ограничена 32К.

dwDataSize – число байт в lpRawData.

lpRawData – произвольный массив байтов. Event Viewer никак не интерпретирует эти данные и отображает их в том виде, в котором они были переданы.

Eventlog предоставляет еще несколько функций (перебрать записи в журнале, найти запись, и т.д.) для работы с журналами событий. Почти все они нужны только для какой-либо программы-анализатора.

Event Viewer при отображении журнала использует очень важную функцию FormatMessage. Мы тоже можем её использовать, чтобы показать сообщение из нашей ресурсной DLL.

          #define ERROR_FROM_WIN32(x) print_error(x)

void print_error(DWORD dwLastError)
{
LPSTR szMsgBuf;
DWORD dwBufLen = 0;

  // Для наших сообщений нужен флаг FORMAT_MESSAGE_FROM_HMODULE, 
  // для системных FORMAT_MESSAGE_FROM_SYSTEM

  DWORD dwFormatFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_HMODULE;

  // Для системных сообщений hRes должен быть NULL

  HANDLE hRes = LoadLibraryEx(«my_msgs.dll”, NULL, LOAD_LIBRARY_AS_DATAFILE);

  dwBufLen = ::FormatMessage(
    dwFormatFlags,hRes, MSG_ERR_1, MAKELANGID(
      LANG_ENGLISH, SUBLANG_ENGLISH_US), (LPSTR)&szMsgBuf, 0, NULL);

  if (dwBufLen)
    cout << “Error: “ << dwLastError << endl;

  ::LocalFree(szMsgBuf);
}

Послесловие

Кому-то это может показаться нудным и даже ненужным занятием. Но логи всегда были очень полезным и действенным способом отладки приложений и устранения ошибок. Использование журналов событий имеет ряд преимуществ:

• Eventlog является «родным» сервисом системы, так почему бы им не пользоваться, тем более что им пользуется сама система?
• Вы можете, например, создать один раз один файл сообщений на всех языках, и все ваши приложения будут его использовать.
• Это дружественный сервис даже для администраторов.
• Вы можете создать свои надстройки над этим сервисом, например, анализатор логов, поиск и фильтрование.

В Windows Vista Microsoft переработала этот сервис. Например, можно генерировать логи в XML, отсылать отчёты о логах и т.д.