Як змістовне журналювання помилок приносить користь розробникам і користувачам

Це вже другий місяць мого стажування в EasyStore, і я хочу висловити свою щиру подяку команді за можливість випробувати себе у світі програмної інженерії. За ці два місяці я отримав безліч нових знань про процеси розробки програмного забезпечення, і одним із ключових уроків стало розуміння важливості “змістовного журналювання помилок” (meaningful error logging). Це не тільки допомагає розробникам під час налагодження та усунення помилок, але й покращує загальний досвід користувачів.

Нещодавно ми провели Різдвяну подію, і це було дуже весело!

Сесія групового фото

Що таке журналювання помилок?

Журналювання помилок — це практика запису інформації про помилки чи події, що відбуваються під час виконання програми.
Журналювання помилок не обмежується лише файлами журналів або журналами бази даних — це може також включати індивідуальні рішення для моніторингу, такі як Rails.logger в Ruby on Rails.

Мета журналювання помилок очевидна:

1. Виявлення та налагодження проблем: Записування необхідної інформації для надання контексту та допомоги в ідентифікації корінної причини проблем.
2. Моніторинг та підтримка продуктивності програмного забезпечення: Слідкування за поведінкою системи для забезпечення надійності.
3. Аудит та відповідність вимогам: Дотримання нормативних вимог або відслідковування несанкціонованого доступу та руху в системі.

Як досягти змістовного журналювання помилок

Хоча журналювання помилок є стандартною практикою, щоб зробити ці журнали “змістовними”, потрібно підходити до цього з розумінням. Змістовні журнали помилок є інформативними та дієвими, дозволяючи розробникам швидко зрозуміти контекст і визначити наступні кроки для вирішення проблеми. Ось кілька найкращих практик:

1.

Будьте описовими

Повідомлення про помилку повинно містити відповідні деталі, такі як очікувана поведінка або параметри, що спричинили проблему.

Приклад:

[ERROR] Не вдалося обробити платіж: Payment ID 12345 недійсне (Отримано: NULL).  
[WARN] Несанкціонована спроба доступу. UserID: 789, IP: 192.168.1.1, Endpoint: /admin.

У цих прикладах повідомлення надають конкретні деталі, такі як ID платежу або IP-адреса користувача, що допомагає ефективніше відстежити корінну причину проблеми.

2. Використовуйте рівні журналювання

Категоризуйте журнали за рівнем серйозності, щоб допомогти розробникам пріоритезувати проблеми:

• DEBUG: Для налагодження та детальної інформації під час розробки.
• INFO: Для документування поведінки системи.
• WARN: Для некритичних проблем, які можуть спричинити майбутні труднощі.
• ERROR: Для критичних проблем, що вимагають негайної уваги.
• FATAL: Для збоїв додатку.

Приклад:

[DEBUG] Виконано запит до бази даних: SELECT \* FROM users WHERE id=5.


[ERROR] Час очікування з'єднання з базою даних перевищив 30 секунд.

3. Включайте стек трейсів

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

Приклад:

[ERROR] Код: DB\_CONN\_001 - Час очікування з'єднання з базою даних.  
Stack Trace:  
 at Database.connect (Database.java:85)  
 at PaymentService.processTransaction (PaymentService.java:140)

4. Використовуйте структуроване журналювання

Журналюйте повідомлення у структурованих форматах, таких як JSON, щоб їх було легше обробляти як розробникам, так і машинам для пошуку.

Приклад:

{  
 "timestamp": "2024-12-23T10:15:30Z",  
 "level": "ERROR",  
 "message": "Не вдалося надіслати електронного листа",  
 "userId": 1023,  
 "emailAddress": "[email protected]",  
 "errorCode": "SMTP\_001"  
}

5. Зробіть журнали дієвими

Коли це можливо, надавайте пропозиції або посилання, що допоможуть вирішити проблему.

Приклад:

[ERROR] Відсутній API ключ у заголовках запиту.


Перейдіть до документації API за посиланням https://docs.example.com/errors#MISSING\_API\_KEY.

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

Змістовні повідомлення про помилки для користувачів

Змістовні повідомлення про помилки важливі не тільки для розробників, але й для користувачів. Добре складені повідомлення про помилки покращують досвід користувачів, зменшуючи їх розчарування та надаючи корисні поради.

1. Будьте чіткими та дружніми

Користувачі повинні відчувати підтримку, а не втрату.

Приклад:

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

2. Будьте прозорими

Проактивно спілкуйтеся про проблеми, щоб викликати довіру користувачів.

3. Надавайте поради

Запропонуйте дієві кроки для вирішення проблеми.

Приклад:

Ваш пароль має містити не менше 8 символів і включати цифру. Будь ласка, спробуйте ще раз.

4.

Відображайте професіоналізм

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

Приклад:

Упс! Щось пішло не так. Наша команда вже повідомлена, і ми працюємо над виправленням. Будь ласка, спробуйте ще раз пізніше.

5. Зменшіть кількість звернень до служби підтримки

Надання корисних повідомлень про помилки мінімізує необхідність звертатися до служби підтримки.

Приклад персоналізованих повідомлень:

Привіт, Алекс, схоже, є проблема з вашим останнім завантаженням. Будь ласка, переконайтеся, що файл у форматі PDF, і спробуйте ще раз.

Рекомендація для розробників Ruby

Для розробників Ruby Slack Ruby Client — це відмінний гем для інтеграції з Web, Real-Time Messaging та Events API Slack.
Ця бібліотека дозволяє розробникам:

• Надсилати повідомлення до Slack через Web API.
• Використовувати реальну передачу повідомлень для миттєвих сповіщень.
• Легко організовувати журналювання помилок та мікроуправління.

Приклад використання: Ви можете надсилати параметри методу у ваш робочий простір Slack для перевірки вхідних даних та забезпечення їх відповідності вимогам.

Остаточні думки

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

Ніхто не любить мати справу з роботизованими, заплутаними повідомленнями про помилки. Вкладення часу в створення описових, дієвих і зручних для користувача повідомлень про помилки приносить користь як розробникам, так і користувачам, що в кінцевому підсумку сприяє успіху програмного забезпечення.

Перекладено з: How Meaningful Error Logging Benefits Developers and Users