Win32: централізоване протоколювання подій

Автор: Серебряков Олексій (Smooky)
QUIBECK INC.
джерело: RSDN Magazine # 3-2007

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

Передмова

Багато з Вас, напевно, брали участь у великих і довгострокових проектах, де розроблялося пристойну кількість модулів, використовувалися численні бібліотеки, сценарії і т.д. Мені теж доводилося брати участь в таких проектах. Один з них і наштовхнув мене на думку про створення цієї статті. У тому проекті брало участь безліч програмістів, розробників і тестерів. Кожен розробник писав невеликий модуль протоколювання (логування, від англ. Logging, - знімати, записувати показання з приладу) і трасування своїх модулів і напрацювань. Хтось писав свої утиліти, які потім розбирали ці протоколи, хтось використовував буферізованние висновок, тобто якогось чіткого регламенту з цієї діяльності не було. Результатом цієї діяльності стало велика кількість розкиданих текстових і бінарних файлів зі зрозумілими і незрозумілими розширеннями, незрозумілого формату і змісту. Зрозуміло, що при такій організації так і повинно було статися. Гірше того, буває і так, що при виході фінальної версії не вдається все це прибрати, і все це виявляється у користувача і замовника.

Для вирішення цієї проблеми операційна система Windows надає такий сервіс і програмний інтерфейс, як Eventlog. Цей інструментарій належить до базових сервісів Windows, тобто поставляється з самою системою і система сама ж його використовує. Варто зауважити, що ця можливість є тільки у систем сімейств WinNT / XP, тому що додаток для протоколювання подій є сервісом. Також варто зауважити, що в Windows Vista і Windows Longhorn цей сервіс істотно перероблений, новий варіант в цій статті розглядатися не буде.

Ми не будемо також розглядати цей чудовий інструмент з точки зору адміністраторів, складальників журналів та інших персон, які покликані управляти системою. Отже, приступимо.

теорія

Малюнок 1.

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

При використанні сервісу протоколювання в журнал слід записувати досить важливі і потрібні відомості про що відбулися помилки, які дійсно потім можуть допомогти розробникам розібратися, що ж сталося з додатком. Не слід, наприклад, писати в системний журнал з періодичністю 100нс повідомлення про те, що користувач випадково видалив файл readme.txt. Журнал подій - це не засіб трасування.

Рекомендації з протоколювання подій

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

Повідомлення в журналі подій - це, перш за все, інформація, здатна допомогти вам, адміністратору і навіть користувачеві зрозуміти, яка проблема виникла в додатку і як її усунути. Зокрема, ця подія може призначатися фахівця технічної підтримки у вашій компанії, і навіть йому буде сумно читати повідомлення: «Процес А не зміг прочитати 0x05 байт 0x2-ого сектора дисковода В». Тому ідеальне повідомлення повинно допомогти користувачеві відповісти на наступні питання:

• Що трапилося і чому?
• Що йому (користувачеві) робити далі?
• Що він (користувач) може зробити, щоб цього більше не повторилося?

Можуть стати в нагоді і наступні рекомендації:

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

Угоди про стилі змісту повідомлення:

• Використовуйте докладні, але прості речення.
• Не використовуйте слова, що складаються з одних заголовних букв.
• Використовуйте точну семантику. Наприклад, замість повідомлення "Bad size" краще все-таки вказати користувачеві правильний розмір.

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

Події в журналі

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

Тип події Пояснення Помилка (Error) Цим типом зазвичай визначається серйозна помилка програми. Наприклад, виконання програми перервалося через брак ресурсів. Попередження (Warning) Цим типом додаток зазвичай інформує про те, що скоро може виникнути проблема, наприклад, закінчиться дисковий простір. Інформація (Information) Цим типом додаток зазвичай інформує про успіх будь-якої важливої ​​операції, наприклад, при старті сервісу. Успішний звіт (Success Audit) Цей тип події зазвичай означає про успіх будь-якої операції доступу, наприклад, користувач увійшов в систему. Чи не успішний звіт (Fault Audit) Цей тип події зазвичай означає, що сталася якась помилка при доступі до ресурсу, наприклад, користувач не зміг звернутися до мережного диска.

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

ПОРАДА

У тексті повідомлення про подію краще не застосовувати символи табуляції і крапку з комою, так як журнал може експортуватися в текстовий файл з роздільниками. Багато організацій імпортують журнали подій в свої бази даних для діагностики своїми засобами. Рядки в форматі UNC краще укладати в трикутні дужки, наприклад <\\ sharename \ servername>.

Елементи журналу подій

журнали

Всю інформацію про екологічні атрибути Вашого журналу сервіс бере з реєстру: HKEY_LOCAL_MACHINE \ SYSTEM \ CurrentControlSet \ Services \ Eventlog.

Кожна гілка в цьому ключі - це журнал. Спочатку їх всього три, але можна створювати свої журнали, і реєструвати свої додатки як джерела подій для цих журналів.

Журнал (Log) Пояснення Додаток (Application) Цей журнал містить записи від додатків. Наприклад, якщо ми зареєструємо своє джерело подій (тобто додаток) і не вкажемо журнал, за замовчуванням записи будуть надходити сюди. Система (System) Цей журнал містить записи, що надходять від системних служб. Але писати в нього може будь-який додаток. Безпека (Security) Цей журнал призначений для аудиту, наприклад, подій входу користувача в систему. Інший (Custom) Можна створити свій журнал. Чи не підтримується в Windows NT.

Контролер домену має ще два додаткових журналу: Directory і File Replication. DNS-сервер також має додатковий журнал, DNS.

Для кожного журналу визначаються ключі. Практично всі вони є обов'язковими і мають значення за замовчуванням, але рекомендується все ж створювати їх для свого журналу.

Ключ в реєстрі Пояснення DisplayNameFile Файл, в якому міститься локалізована рядок з назвою журналу, тобто рядок, яку покаже Event Viewer. Якщо параметр не вказано, Event Viewer як рядки покаже найменування підключа, в якому визначено параметр. За замовчуванням всі локалізовані ресурси знаходяться в% SystemRoot% \ system32 \ ELS.DLL. Строковий параметр. DisplayNameID Ідентифікатор рядка в ресурсної DLL. Тип параметра DWORD. File Шлях до папки, де Event Viewer буде зберігати файли журналів. За замовчуванням це% SystemRoot% \ system32 \ config \ MyLogName, де MyLogName - ім'я журналу. При створенні нового файлу журналу сервіс повинен мати права на повний доступ до файлу. Якщо значення цього параметра буде невірним, всі записи будуть перенаправлятися в журнал Application. В дорозі не можна використовувати ім'я віддаленого комп'ютера, DOS-пристрої, дисководи, іменовані канали. Не можна використовувати змінні оточення, які не можна розкрити в контексті сервісу. MaxSize Максимальний розмір журналу в байтах. За замовчуванням 512К. Параметр DWORD. PrimaryModule Найменування ключа, де зберігаються настройки за замовчуванням. Зазвичай збігається з найменуванням журналу. Строковий параметр. Retention Інтервал в секундах, протягом якого записи можуть залишитися не перезаписати. Якщо встановлено в нуль, записи в журналі завжди перезаписувати, якщо не нуль або 0xFFFFFFFF, то записи ніколи не перезаписувати. При досягненні максимального розміру журнал необхідно очистити вручну, інакше записи будуть втрачені. Перед тим, як змінювати це значення, журнал необхідно очистити. Параметр DWORD. За замовчуванням - 0. Sources Список додатків, сервісів, які можуть писати в журнал. Тільки для читання. Цей список створює сам сервіс. Назви додатків беруться з поточної гілки журналу і поділяються null-terminated. Параметр багатостроковий. AutoBackupLogFiles Якщо значення параметра - 0, журнал не зберігається як резервна копія. За замовчуванням - 0. RestrictGuestAccess Якщо значення - 1, то користувачі під обліковим записом Guest і Anonymous не мають доступу до журналу. За замовчуванням - 0. Isolation Не використовується.

джерела подій

Кожна подветкой в ​​гілці Eventlog - це джерело подій.

Наприклад, для додатка MySuperApp.EXE, яке буде записувати події в журнал Application, необхідно створити таку подветкой:

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

Тут MySuperApp - це довільне ім'я, по якому сервіс (журнал) буде впізнавати події, що надходять від нашого застосування. Яких-небудь угод про ім'я в документації не зазначено, але мабуть, ім'я має бути унікально в межах однієї подветкой. Зазвичай використовується назва програми чи модуля. По суті справи, це і є реєстрація додатки в сервісах Event Logging і Event Viewer.

Саме це ім'я буде передаватися функції RegisterEventSource, яка поверне описувач (handle) журналу.

Користувальницькі додатки і сервіси повинні або реєструвати себе в журналі Application, або створювати свій журнал. Журнал Security використовується тільки системою. Драйвери пристроїв повинні використовувати журнал System.

Кожен джерело подій (як ми вже знаємо, додаток) повинен у своїй подветкой визначити перераховані ключі. Вони допомагають Event Viewer зіставляти повідомлення і підставляються параметри з ресурсної DLL-бібліотеки з ідентифікаторами в додатку (пізніше я це продемонструю на прикладі):

Ключ в реєстрі Пояснення CategoryCount Число використовуваних категорій. Тип DWORD. CategoryMessageFile Шлях до файлу з локалізованими рядками, визначальними категорії. Строковий параметр. EventMessageFile Шлях до файлу з локалізованими рядками повідомлень. Можна перерахувати декілька файлів через кому. Наприклад, EVT_ENG.DLL, EVT_RUS.DLL. Строковий параметр. ParameterMessageFile Шлях до файлу з локалізованими рядками параметрів, підставляється в текст повідомлення. Строковий параметр. TypeSupported Параметр визначає типи підтримуваних повідомлень. Наприклад, тільки помилки і попередження: EVENTLOG_ERROR_TYPE | EVENTLOG_WARNING_TYPE. Параметр DWORD визначає маску з наступних типів: EVENTLOG_ERROR_TYPE, EVENTLOG_WARNING_TYPE, EVENTLOG_INFORMATION_TYPE, EVENTLOG_AUDIT_SUCCESS, EVENTLOG_AUDIT_FAILURE

Фактично виходить, що коли додаток викличе функції RegisterEventSource або OpenEventLog, сервіс Eventlog буде шукати в реєстрі гілку MySuperApp, щоб повернути описувач журналу. Якщо він не знайде гілку з ім'ям MySuperApp, за замовчуванням буде використаний журнал Application.

ПОПЕРЕДЖЕННЯ

Однак якщо гілка була знайдена, але не були визначені файли повідомлень для знайденого джерела подій, то при відкритті Event Viewer повідомить про помилку. Тому хорошим тоном буде, не тільки зареєструвати джерело подій, а й надати файли повідомлень.

Малюнок 2.

Ось, власне, основні теоретичні відомості. Можна приступити до практичних занять.

Практика

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

файл повідомлень

Категорії, повідомлення і підставляються параметри можна розмістити як в одному файлі, так і в різних. Для зручності і наочності розмістимо все в одному файлі MYEVT_ENG.MC.

категорії подій

Категорії подій - це всього лише числові ідентифікатори, які допомагають фільтрувати записи при перегляді журналу в Event Viewer. Кожен джерело подій може позначити свої категорії будь-яким числом. Треба тільки врахувати, що вони повинні розташовуватися на початку файлу повідомлень послідовно (по порядку) і починатися з 1. Детальний опис формату файлу * .MC можна знайти в в MSDN.

файл MYEVT_ENG.MC

; 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); ; ; ; ; 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):

3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 7 6 5 4 3 2 1 0 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Severiry CR Facility Code

Важливість помилки (Severity):

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

Належність (Customer bit):

• 0 - Системний
• 1 - для користувача
• Зарезервований (R)
• Код підсистеми (Facility)
• Код помилки (Code)

Докладні пояснення можна знайти в книзі Ріхтера або в MSDN.

рядки повідомлень

Тепер визначимо рядки повідомлень, що пояснюють подію. Рядки повідомлень можуть містити підставляються параметри.

Файл MYEVT_ENG.MC (продовження)

; 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; 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:

В результаті ми отримаємо файл MYEVT_ENG.RES. І, нарешті, скомпілюємо бібліотеку:

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

Тепер нам залишилося зареєструвати джерело подій і написати код, який використовує журнал подій. На жаль, Microsoft не надає ніяких утиліт для реєстрації джерела подій (мені, принаймні, вони невідомі), тому робити все доведеться ручками. На цільовій машині це можна зробити лише один раз, наприклад, при інсталяції.

Один і той же файл повідомлень можуть використовувати кілька додатків. І навіть якщо повідомлення написані на різних мовах, вони все одно можуть перебувати в одному ресурсному файлі.

Реєстрація джерела подій

Для реєстрації джерела подій досить усього лише визначити кілька ключів в реєстрі (опис ключів наведені вище).

Реєстрація джерела подій

TCHAR szAppLog [MAX_PATH] = _T ( "\\ SYSTEM \ CurrentControlSet \\ Services \\ Eventlog \\ Application \\ MySuperApp"); TCHAR szMsgFile [] = _T ( "my_msgs.dll"); DWORD dwCategoryCount = 3; 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 - показувати їх. Залишилося тільки це використовувати.

Використання журналу подій

Використання журналу подій (use_my_events.cpp)

#include <windows.h> #include <iostream> #include <tchar.h> #include "myevt_eng.h" #pragma comment (linker, "/ subsystem: console") #pragma comment (lib, "advapi32.lib" ) using namespace 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.

Використання FormatMessage

#define ERROR_FROM_WIN32 (x) print_error (x) void print_error (DWORD dwLastError) {LPSTR szMsgBuf; DWORD dwBufLen = 0; DWORD dwFormatFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_HMODULE; 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, відсилати звіти про логах і т.д.