[Перевод] 10 лучших приёмов логирования для разработчиков17.12.2024 15:15

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

Качественное логирование играет принципиальную роль для высокой производительности и целостности системы в современных сложных ИТ-средах. Эффективное логирование оптимизирует устранение сбоев, так как из лога можно получить однозначную информацию об ошибках и поведении системы. Кроме того, оно улучшает мониторинг производительности, показывая узкие места и отклонения. Надёжное логирование важно и для безопасности: оно помогает выявлять и расследовать потенциальные угрозы или случаи несанкционированного доступа.

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

Логи — это записи событий, действий и сообщений, генерируемых приложением или базовой ИТ-инфраструктурой во время работы. В сообщениях лога содержатся тонны полезной информации о системе: описание события, метка времени, степень серьёзности проблемы, возникшей из-за этого события, и другие метаданые. Логи полезны для отладки багов, диагностики ошибок и аудита активности системы. Из них можно почерпнуть текстовое описание системных событий, а значит, с их помощью можно гарантированно понять, что произошло и что в связи с этим следует предпринять.

1. Структурируйте логи

В неструктурированных логах трудно выполнять парсинг, поиск и анализ. Используйте структурированные логи (например, JSON или XML): это позволяет обрабатывать данные логов программными средствами, сопоставлять их с другими логами и использовать в инструментах мониторинга и анализа. Структурированные логи проще читать, а на основе извлечённой информации легче принимать решения. Это позволяет команде разработчиков и админов быстрее находить нужную информацию.

Пример: файл log.json

{
  "timestamp": "2024-09-18T12:00:00Z",
  "level": "INFO",
  "message": "User login successful",
  "user_id": "123456",
  "session_id": "abcde12345"
}

Этот приём помогает работать с логами как со структурированными событиями везде, где это только возможно.

2. Объединяйте логи в момент создания

Объединение нескольких взаимосвязанных записей лога в одно связное событие сокращает объём журнала, повышает ясность информации и упрощает анализ лога. Не стоит заносить в лог каждый этап процесса по отдельности. Вместо этого соберите соответствующие детали: статус действий, метки времени и другие важные сведения — в одну структурированную запись.

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

Несколько записей лога:

"time": "2024-09-18T12:00:00Z", "level": "INFO", "message": "User authentication started", "user_id": "123456"
"time": "2024-09-18T12:00:01Z", "level": "DEBUG", "message": "Checking user credentials", "user_id": "123456"
"time": "2024-09-18T12:00:02Z", "level": "INFO", "message": "User credentials verified", "user_id": "123456"
"time": "2024-09-18T12:00:03Z", "level": "INFO", "message": "Generating session token", "user_id": "123456"
"time": "2024-09-18T12:00:04Z", "level": "INFO", "message": "Session token generated", "user_id": "123456", "session_id": "abcde12345"
"time": "2024-09-18T12:00:05Z", "level": "INFO", "message": "User login successful", "user_id": "123456", "session_id": "abcde12345"

Одна запись лога:

"time": "2024-09-18T12:00:00Z", "duration_ms": "5000", "message": "User login authenticated", "user.credentials.verified”: true, "request_id": "req-789xyz", "user_id": "123456", "session_id": "abcde12345"

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

Если трудно собрать всю информацию в один вызов логгера, можно создать спан для отслеживания событий. Добавить в спан информацию можно на любом этапе, пока работа не закончена.

3. Используйте уникальные идентификаторы

Если запрос поступает в систему извне, создайте уникальный идентификатор запроса и применяйте его на всех этапах обработки данных по этому запросу.

В идеале каждый сервис в вашей системе выдаёт одну каноничную запись лога, на которую ссылается уникальный идентификатор, например поле request ID или trace ID. Эти идентификаторы помогают быстрее устранять сложные проблемы и отслеживать конкретные действия, запросы или пользователей в системах и сервисах.

4. Стандартизируйте названия и типы полей в структурированных логах

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

5. Не включайте в логи конфиденциальную информацию

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

Пример:

Перед маскированием:

Password: 12345678

После маскирования:

Password: *****

6. Обращайтесь с логами как с данными

Без эффективного анализа даже хорошо структурированные логи могут стать сумбурными и неуправляемыми: в них будет сложно выявлять закономерности и аномалии или отслеживать первопричины проблем. Фильтруйте логи. Используя комбинацию полей (например: request ID, user ID, URL-путь или коды ошибок) можно сузить целый лог до нужных записей. Это ускорит устранение неполадок и позволит сосредоточиться на аналитических данных, на основании которых можно действовать.

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

7. Используйте централизованную систему управления логами

В распределённых системах логи часто разбросаны по разным сервисам, серверам и регионам. Это затрудняет объединение логов и управление ими. Лучше собирать, объединять и анализировать логи в одном месте. Используйте для этого централизованную систему управления логами, например: Elasticsearch, Splunk или Honeycomb (как вариант, отправляйте данные лога с помощью OpenTelemetry). Такой подход ускоряет поиск, анализ логов и улучшает корреляцию между сервисами.

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

8. Настройте срок хранения записей в логе

Логи полезны для устранения проблем, аудитов и комплаенса. Но всё же их не стоит хранить вечно. Сформируйте политики хранения записей, чтобы автоматически архивировать или удалять старые логи по прошествии указанного периода. Это сокращает затраты на хранение данных и обеспечивает соблюдение таких норм по их защите, как GDPR и ФЗ №152 «О персональных данных».

9. Настройте оповещения

Логи нужны не только для документирования истории событий. Логи могут в реальном времени отправлять оповещения о критически важных сбоях. Настройте оповещения для логов уровня ERROR или FATAL.

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

Надёжная стратегия анализа логов включает оповещения, чтобы команда разработчиков могла быстро реагировать на инциденты прежде, чем это выльется в серьёзные проблемы.

10. Документируйте форматы логов и приёмы работы

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

Документация должна содержать следующие разделы:

Спецификация формата лога (поля, типы данных);
Определения уровней лога;
Политика хранения записей;
Правила обращения с конфиденциальными данными;
Инструменты и системы логирования.

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

Или открыть перспективы и получить повышение с профессиональным обучением и переподготовкой: